OPEN SOURCEMITALPHABUILT FOR CLAUDE CODE

Bitácora

Every bit of context, logged.

Terminal demo: /bitacora:handoff writes a [CTX] comment to the ticket, /clear wipes the session, and /bitacora:resume restores the context. — Scripted demo — handoff logs a `[CTX]` comment, `/clear` wipes the session, resume restores it. Output condensed for readability.

01 · WHAT IT IS

Jira as a shared memory layer

Bitácora is a small Claude Code plugin that turns Jira into a shared, structured memory layer across sessions and teammates. It composes with the tools you already use — the Atlassian Rovo MCP for Jira, Claude Code as the host — and adds the workflow on top: opinionated commands for handing off, resuming, reporting status, picking work, and sharpening vague tickets.

02 · THE PROBLEM

Long sessions degrade

The context window fills up, attention spreads, decisions drift. The honest move is to clear and start fresh — but resuming cleanly needs a structured handoff somewhere. Keep it in your head and it dies with the session. Keep it in Jira, where the work already lives, in a format other agents can read, and you get something better than personal memory: a record the whole team can pick up.

03 · HOW IT WORKS

The handoff loop

1. Handoff. /bitacora:handoff writes a structured [CTX] comment to each touched ticket — Status, Done, Decisions, Next.
2. Clear. Run /clear with a clean conscience — the durable state is safely on the ticket.
3. Resume. /bitacora:resume pulls that [CTX] back into a fresh session. You — or a teammate — are exactly where the last session left off.

04 · THE FORMAT

A strict [CTX] comment format

Bitácora writes Jira comments in a versioned, structured format so agents and humans parse them reliably. State-reading commands look at [CTX] comments only — free-form discussion is ignored.

JIRA COMMENT · [CTX] v1

[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

05 · COMMANDS

The command surface

/bitacora:handoff

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

/bitacora:resume

Rehydrate a fresh session from a ticket's latest [CTX] — pull its Status / Decisions / Next back into context after a /clear.

/bitacora:status

Synthesize one ticket's latest [CTX] into an audience-tailored summary (self / eng / ops / pm / exec). Read-only.

/bitacora:digest

Aggregate read — roll up an epic across its children, or read a multi-ticket scope (--mine / --sprint / --jql) with --blocked / --standup lenses.

/bitacora:next

Morning ticket picker. Categorizes your assigned tickets by pickup cost, recommends one, and chains into resume.

/bitacora:improve

Sharpen a vague ticket — corpus-grounded structured rewrite, with a snapshot to an [ARCHIVE] comment before any edit.

/bitacora:help

Print the full Bitácora command reference.

06 · WHY USE IT

Built to be trusted

Shared, not personal

State lives on the ticket in Jira, in a format other agents and teammates can parse — not trapped in one person's local memory.

Public source

Plain files in directories you can grep. You always know exactly what it does.

No telemetry, no auto-update

Nothing on your machine changes unless you re-install or move your pin.

Every write is gated

Bitácora confirms before it writes to Jira — and warns before burying a teammate's recent [CTX].

07 · INSTALL

Get it running

Submit each command separately in Claude Code. You'll need git, jq, and bash on your PATH, plus the Atlassian Rovo MCP for Jira read/write access.

CLAUDE CODE

# submit each line separately
/plugin marketplace add fr1j0/bitacora
/plugin install bitacora@bitacora
/reload-plugins
/bitacora:help

/plugin — add the marketplace
/plugin — install the plugin
/reload-plugins — register commands and hooks
/bitacora:help — verify

It's alpha and in active development — pin to a tagged release you've audited if you need stability.

08 · CONTRIBUTING

Issue-first, every change

Bitácora is alpha and single-maintainer, so the flow is kept deliberately simple — every change starts as a GitHub issue.

1. Open an issue. Pick a template — bug, feature, or question.
2. Wait for triage. A maintainer closes it, asks for more info, or labels it ready-for-dev.
3. Branch off main. Cut a topic branch <type>/issue-<N>-<slug> — never push to main directly.
4. Open a PR. Include Closes #N; an automated check enforces that the linked issue is ready-for-dev.

Full guidelines, security policy, and licence are linked in the Project docs panel.