Bitácora

Every bit of context, logged.

Structured session handoffs, logged to your issue tracker — Jira or GitHub Issues — so context survives context clears, sessions, and teammates.

Scripted demo — output condensed for readability.

bit·ácora — Spanish for "ship's logbook": the structured journal kept aboard a ship to record position, decisions, and observations across long voyages.

Bitácora is a Claude Code plugin that turns your issue tracker — Jira or GitHub Issues, selected per-repo — into a shared external memory layer for engineering teams — capturing structured handoffs across sessions and rehydrating them on resume, so context survives context clears. It ships the full read/write loop: handoff, resume, status (single-ticket) and digest (epic rollup + multi-ticket reads), a morning next picker, an improve rewriter for vague tickets, help, an opt-in statusLine context meter, and the [CTX] comment-format discipline.

Note

Beta (0.x) — the core loop is complete; the command surface is still settling. Commands or flags can change between minor releases. Pin to a tagged release you've audited if you need stability.

---

At a glance

• What — a Claude Code plugin that uses your issue tracker (Jira or GitHub Issues) as a shared, structured memory layer across sessions and teammates.
• How — a strict [CTX] comment format plus opinionated commands for handoff, resume, status, morning ticket picking, and corpus-grounded ticket sharpening.
• Today — the core loop complete, plus v0.8.0: pluggable tracker backends — every read/write skill now targets Jira or GitHub Issues (selected per-repo; GitLab seam stubbed for a follow-up) — on top of handoff (with collision detection — warns before burying a teammate's recent [CTX], or stacking a duplicate self-handoff), resume, status (single-ticket reads, now with a staleness signal — flag a [CTX] that's fallen behind the ticket's activity), and digest (epic rollup + multi-ticket scopes — --mine/--sprint/--jql with --blocked and a done/planned/blocked --standup lens, plus a parked-debt ledger in the aggregate; ticket keys linked when copied for Slack), next, improve, help, the [CTX] format, and an opt-in statusLine context meter.
• Safety — public source, no auto-update, no telemetry, and every tracker write is confirmation-gated.

Stability & compatibility

Bitácora is beta (0.x) — the core read/write loop is complete, but the command surface is still settling, and commands or flags can change between minor releases (e.g. v0.7.0 moved multi-ticket reads out of /status into /digest). Pin to a tagged release you've audited if you need stability.

What we're deliberate about, by layer:

• The [CTX] comment format — the real contract. People and other agents parse these comments, so the format is versioned and treated as the stable surface. Current version v1; the required [CTX] + Status:/Next: shape won't break within v1, new sections are additive, and a breaking change bumps to [CTX v2]. See the format spec.
• Commands & flags — still settling. Names/options may change in 0.x; breaking moves are noted in the CHANGELOG and, where possible, self-redirect (/status --mine points you to /digest).
• Config keys — additive with fallback. New keys ship with defaults; renamed keys keep reading the old name (digest.* falls back to status.*).

No telemetry, no auto-update — nothing on your machine changes unless you re-install or move your pin.

What it does

Bitácora is a small plugin that builds on the Claude Code ecosystem:

• A tracker backend — the Atlassian Rovo MCP for Jira-backed repos, or the gh CLI for GitHub Issues (a GitLab seam is stubbed for a follow-up). Selected per-repo: an explicit tracker: in .bitacora.yml wins, otherwise inferred from the git remote host. (required — whichever matches your tracker)
• Remember (or a claude-mem-compatible plugin) — local session memory across context clears (optional companion)

What Bitácora adds on top is the tracker-aware workflow layer: opinionated commands for handing off, resuming, reporting status, picking work, and sharpening vague tickets — plus a comment-format discipline that lets agents read each other's structured updates across sessions and team members.

What lives where — status vs. scratch

Bitácora's job is status — the durable, ticket-level narrative a teammate would care about: where the work stands, the decisions behind it, and what's next. That belongs in the tracker, on the ticket, in the open. That's what [CTX] comments are. /bitacora:improve extends the same principle to the ticket itself — sharpening a vague description or title is durable, shared, in-the-open work too, just on ticket fields instead of comments.

What Bitácora deliberately doesn't manage is the high-frequency scratch between sessions — the running breadcrumbs, the small "just did X" notes, the granular working state that turns over every few minutes. That data is local, personal, and churny, and it has its own tools:

• Remember — local session memory across context clears (the .remember/ buffer)
• claude-mem — a Remember-compatible alternative
• Any memory MCP server, or Claude Code's built-in CLAUDE.md memory

Two altitudes: the tracker holds the milestones the team needs; your local memory tool holds the minute-to-minute scratch only you need. Bitácora owns the first and stays out of the second — which is why Remember is optional, not required.

Commands

The flagship command — wrap up a session cleanly:

/bitacora:handoff

Writes a structured [CTX] comment to each touched ticket, plus a local handoff for next-session continuity.

All commands below are shipped, and every one of them works against Jira or GitHub Issues (see What it does for backend selection).

Command	What it does
/bitacora:handoff	Wrap up a session cleanly. Writes a structured [CTX] comment to each touched ticket plus a local handoff for next-session continuity.
/bitacora:help	Print the Bitácora command reference.
/bitacora:resume	Rehydrate a fresh session from a ticket's latest [CTX] — pull its Status / Decisions / Next back into context after a /clear, closing the handoff loop from the tracker (not just local Remember).
/bitacora:status	Synthesize ONE ticket's latest [CTX] into an audience-tailored summary (--for-self/-eng/-ops/-pm/-exec). Epics render as a single node (their own [CTX], not a rollup). Read-only: prints and offers a clipboard copy.
/bitacora:digest	Aggregate [CTX] read — roll up an epic across its children, or read a multi-ticket scope (--mine, --sprint, --jql, or 2+ keys) for a cross-ticket digest (with a parked-debt ledger) or a query lens — --blocked (what's stuck) or --standup (done / planned / blocked). Read-only: prints and offers a clipboard copy.
/bitacora:next	Morning ticket picker. Reads the tickets assigned to you, categorizes by pickup cost (Continue / Ready / Quick wins + a Needs-attention tail), annotates each with a [CTX]-grounded reason-to-pick, recommends one, and chains into /bitacora:resume <KEY>. Read-only.
/bitacora:improve	Sharpen a ticket — corpus-grounded structured rewrite (Story / Bug / Epic / Subtask aware) with a snapshot to an [ARCHIVE] comment before any field edit. Read + write; description by default, title opt-in per invocation.

Shipped commands also have a shorter, opt-in /bit: alias (e.g. /bit:handoff, /bit:help) — see the plugin README.

✅ statusLine (opt-in) — a single-line context-window meter that bolds red at ≥85% so you know when to /bitacora:handoff then /clear + /bitacora:resume. Also shows the active ticket and a ✎ handoff pending marker. Opt-in setup in the plugin README.

Why this exists

The short version: long Claude Code sessions degrade. The context window fills up, attention spreads, decisions drift. The honest move is to clear and resume — but resuming cleanly requires a structured handoff somewhere. And if you do that handoff in the tracker (where work already lives), in a format other agents can read, you get something better than personal memory: a shared external memory layer for the whole team.

The longer version: a tool you trust with your workflow should be one you can fully inspect and control. Bitácora is built on that principle — public source, no auto-update, no telemetry, just plain files in directories you can grep. You always know exactly what it does, and nothing changes unless you change it.

Architecture

Bitácora is intentionally small. It composes with existing tools rather than replacing them.

  Bitácora — commands + the [CTX] comment-format discipline
                          │
                          │  layers on top of
                          ▼
  ┌───────────────────────────────┬─────────────────────┐
  │      tracker backend          │     Claude Code     │
  │  · Atlassian Rovo MCP (Jira)  │       (host)        │
  │  · gh CLI (GitHub Issues)     │                     │
  │  · glab CLI (GitLab — soon)   │                     │
  └───────────────────────────────┴─────────────────────┘

  Optional companion · local scratch layer:
      Remember / claude-mem / memory MCP — the between-sessions notes

At minimum you need one tracker backend — the Atlassian Rovo MCP for Jira, or the gh CLI for GitHub Issues — and Claude Code itself. Remember is optional but recommended — it's where the high-frequency scratch lives, separate from the ticket-level status Bitácora owns (see What lives where).

Installation

Submit each command separately in Claude Code — pasting all four in one prompt will be read as a single argument and fail.

1. Add the marketplace.

/plugin marketplace add fr1j0/bitacora

Successfully added marketplace: bitacora

2. Install the plugin.

/plugin install bitacora@bitacora

✓ Installed bitacora. Run /reload-plugins to apply.

3. Reload to register commands and hooks.

/reload-plugins

Reloaded: N plugins · M skills · …

4. Verify.

/bitacora:help

Prints the Bitácora command reference.

The two opt-in surfaces — the statusLine and the /bit: aliases — are documented inline in the plugin README; pick them up when you want them.

Prerequisites

• git, jq, and bash 3.2+ on PATH. jq is required by the handoff guardrail hook; without it the guard fails open with a one-line stderr note rather than silently disabling.
• A tracker backend matching where your tickets live — selected per-repo via tracker: in .bitacora.yml, or inferred from the git remote host (see the plugin README):
  • Jira — the Atlassian Rovo MCP configured with read/write access to your team's Jira instance.
  • GitHub Issues — the gh CLI installed and authenticated.
  • (Without any backend, handoff runs local-only — drafting comments to screen instead of writing them.)
• The Remember plugin or another local memory tool (optional — for the between-sessions scratch Bitácora delegates rather than manages).

Pinning to a specific revision. The marketplace points at main. To pin to an audited revision, check out a tagged release — the latest is v0.8.1 — or fork the repo and marketplace add <your-fork>, or git clone and install as a directory source (see Claude Code's plugin docs).

Troubleshooting — /bitacora:help says "Not logged in" after /login. The in-session /login writes the auth token to disk but doesn't always refresh the running Claude Code process's in-memory auth state — most likely on a freshly bootstrapped profile where Claude Code prompted for login during the session. Restart the session: Ctrl+C, re-run claude (or HOME=/whatever claude if you're testing in an isolated profile), then /bitacora:help should work. Sessions that were already logged-in before the install are unaffected.

The [CTX] comment format

Bitácora writes ticket comments in a strict structured format — the same tracker-agnostic format on Jira and GitHub — so other agents (and humans) can parse them reliably:

[CTX] Status update

Status: In Progress

Done:

- OAuth provider client implemented
- Callback handler happy path complete

Decisions:

- PKCE flow over implicit (more secure for SPAs)

Next:

- Token refresh implementation

Agents reading the ticket for /bitacora:resume, /bitacora:status, /bitacora:digest, /bitacora:next, or cross-ticket queries use only [CTX]-prefixed comments — free-form human discussion is ignored for state extraction. (/bitacora:improve and /bitacora:handoff's continuity-read are the lenient exceptions: they read everything, because requirements and prior-handoff context often live in human discussion.)

This creates a virtuous loop: the more team members adopt the format, the more useful the shared memory layer becomes. See docs/JIRA_AGENT_COMMENT_FORMAT.md for the full spec.

Philosophy and safety

Note

These aren't features — they're structural commitments, baked in from the start so you can trust the tool with your workflow.

• Public source. Read every line. No black boxes.
• No auto-update. Plugin updates happen only when you explicitly run /plugin install again. No version you didn't choose will land on your machine.
• No telemetry. Bitácora does not phone home. No analytics, no usage tracking, no third-party reporting.
• Pin to a commit if you want. Fork and lock to a specific revision for full reproducibility.
• Confirm before writing. Bitácora never writes to your tracker without showing you the draft first. There is no "trust mode" that bypasses this.

What Bitácora is not

• Not a memory system. That's Remember (or claude-mem).
• Not a tracker client. That's the Atlassian MCP (Jira) or the gh CLI (GitHub).
• Not a context compressor. It doesn't shrink your live context window — it helps you hand off cleanly and resume, so you can afford to /clear.
• Not a replacement for your judgment. Every tracker write is confirmation-gated; you decide what goes up.

Bitácora is the glue — the opinionated workflow layer that ties these tools into a coherent, team-aware ticket lifecycle.

Contributing

Beta, single-maintainer. Issues and design discussion are welcome — every change starts as a GitHub issue; see CONTRIBUTING.md for the issue-first flow and maintainer guardrails. If you need full reproducibility, fork and pin to a commit you've audited.

License

MIT — permissive, allowing commercial and private use. The one commitment beyond MIT's terms: the project itself will not auto-update users into surprises.

About the name

Bitácora comes from the Spanish bitácula, from the Latin habitaculum — "a dwelling place." Originally it referred to the wooden housing on a ship's deck that held the compass, and by extension to the captain's logbook kept inside it.

It has no etymological relationship to the English word "bit." But it's a coincidence too good not to use.

---

Bitácora. Every bit of context, logged.