katra

katra

A committed, rich-component dev log you write as you build — for a developer working solo or alongside a coding agent — and the memory that makes spec-driven agentic development work. Markdown entries with embedded interactive components, stamped automatically with the commit and diffstat they describe, served as a live, auto-reloading page.

It exists to make one workflow reliable: *chronicle the work as it happens — the why, the dead ends, the screenshots and animations — and never lose a draft to a "promote" step that gets skipped.*

The same store is what keeps an agent effective across sessions: designs land as committed specs, tasks point at them, and a session starting cold reads the spec instead of re-deriving intent from a conversation that no longer exists. That loop is the agent workflow below.

katra init --install-hook        # store + portable Git auto-stamp

katra new "Reworked the swing" # start a draft (a markdown file) katra capture shot.png # drop a screenshot into it katra compare before.png after.png katra serve # live page on the LAN, reloads as you write git commit -m "…" # the draft is stamped with this commit

The one idea

A draft is an entry with no commit hash. That is the entire state machine.

It appears in the *In Progress* panel the moment you create it. There is no scratch file, no separate document, no "publish" toggle. Stamping it — adding the hash and the diffstat — is what drops it into the log.

Everything else follows from that. Nothing can get stranded in a buffer you forgot to promote, because there is no buffer. The log ends up in the order you actually worked, including the parts that did not pan out, which is the half a squashed history always loses.

The viewer

katra serve renders the store as a live page — no build step, no static site to regenerate while you write. The spine down the middle is the log in the order it happened: future epics, the entry in flight right now, then the past. The right rail surfaces what a flat file list buries — decisions that are still load-bearing, and which tags a stretch of work threads through.

More screenshots

An entry, open — this one shipped mid-draft with a before/after slider comparing two icon-mark directions, dragged in with katra compare:

The board, grouped by status — specced is its own column between todo and doing, for the tasks that have a committed design and nobody building them yet:

The hub, one page across every registered project on the machine — this is the maintainer's own, 14 projects and 25 things in flight at once, none of them re-typed anywhere:

The problem

You finish a hard week. The commits say fix streaming, wip, actually fix streaming. Six months later you need to know *why* the spawn budget is nearest-first, and the answer is not in the diff — it was in your head, and in a screenshot you no longer have.

The usual answers are all bad in the same way: they are a second job.

• A CHANGELOG.md records what shipped, not what you learned, and it is written at release time from the diff you are trying to explain.
• A wiki or a Notion page is not in the repo, so it drifts from the code immediately and is not there when someone clones.
• A blog post is written afterwards, from memory — which is exactly when the detail you needed is gone.
• Conventional commits give you a machine-readable *what* and no room for a *why*, a picture, or an alternative you rejected.

The common failure is that all of them are a step *after* the work, and any step after the work gets skipped when the work runs long — precisely when the log would have been worth most.

katra's bet is that the log has to be a side effect of working rather than a task that follows it. So the draft is created when you start, it accumulates screenshots and reasoning while you go, and the commit you were going to make anyway is what publishes it.

The agent workflow

This is what katra is built around, and the reason its shape is odd compared to a static-site generator: it exists to keep two things from being lost between agent sessions — the design an agent is meant to build from, and the record of how the build actually went.

An agent that logs at the end writes a summary of a diff — the one thing the diff already tells you. What is lost is everything before the final state: the approach that failed, the measurement that changed the plan, the picture of the bug. So katra pushes the log *into* the work. The common contract is the CLI sequence in The Katra workflow: declare the epic/task, attach and read a committed spec when one is warranted, open the draft before implementation, record decisions and evidence as you go, then stamp and close. It works from Codex, Claude Code, MCP, or a plain shell.

katra init --install-hook

That creates the Katra and installs the harness-neutral Git post-commit auto-stamp. Claude Code users can additionally run katra setup, which installs its skill and seven session hooks. With that optional adapter:

1. `SessionStart` reports the active draft, unresolved memory, or in-flight changes that need reconciling.
2. `PostToolUse` records every file the agent edits.
3. `Stop` blocks the turn from ending if authored code changed and nothing declared what it was for.
4. `PreToolUse` blocks a git commit whose staged code has no reconciliation receipt.
5. Your commit fires the post-commit hook, which stamps the draft.

The gate is the part people react to, so it is worth being precise about when it fires. It blocks only when the turn authored code that is still present in the working tree, outside the katra directory, and nothing declared its purpose. A conversational turn never blocks. An edit-then-revert nets to nothing and never blocks. Someone else's pre-existing dirt is not your work and never blocks. A blocked turn never blocks twice for the same unchanged work.

To satisfy it — is a slug from katra task list (or create one with katra task new):

katra reconcile --advance <task>   # this moves a task forward

katra reconcile --close # this finishes one katra reconcile --no-task --reason "…" katra reconcile status # what does the gate want right now?

If you are trying katra out, use `katra setup --no-gate`. You get the nudges and the auto-stamp without anything blocking a commit, and you can turn the gate on later by re-running katra setup. A blocking hook in every repository is a real change to how committing feels, and it should be a choice made on purpose.

There is also an MCP server (katra-mcp) for clients that would rather call a tool than shell out. Its fifteen tools cover entries plus tasks, task specs, epics, decisions, and articles. Full detail: The Katra workflow and Agents.

When the first release ships, the official MCP Registry will be able to discover the same stdio server through a narrow OCI package. That image contains only katra-mcp and git; it exists because the registry needs an installable package, not because a container is a better way to use Katra. A registry client still has to expose the repository working tree to it. For direct use, install the native binaries above.

Spec-driven, not spec-derived

Current-source feature: the installed v0.1.0 CLI does not yet have

task spec, task new --spec, or the specced list-filter help value.

Build current source with make all for this phase until the next release;

the release checklist now asserts all three against the packaged binary.

A task can carry spec: — a node slug in the katra (a decision, an article, an entry) or a path relative to the repository root, resolved the same way as a [[wikilink]]. katra task spec attaches it, and moves the task from todo (or empty) to a new status, specced: *a design exists, committed, and nobody has started building it.*

katra task new "Cache swap"                           # todo, slug: cache-swap

katra decide "Cache invalidation: TTL, not events" # write the design katra task spec cache-swap cache-invalidation-ttl-not-events # by node slug katra task start cache-swap # -> doing, implement from it

The benefit is implementation efficiency and it compounds across sessions: an agent starting cold — new context window, different day — reads the spec instead of re-deriving intent from a conversation that no longer exists. katra task list --status specced is the worklist. Nothing requires a spec; todo → doing is still legal, and most tasks don't warrant one. specced is just a place to stand between "we should do this" and "someone is doing it," for the tasks where a design is worth writing down first — and the entries you write while implementing become the other half of the record: what the spec proposed against what actually happened, dead ends included.

Optional Claude Code memory ingest

Claude Code keeps native per-project memory. katra can ingest it into a private ledger, so the log gets the play-by-play without anyone re-typing it. Only metadata.type: project memories are admitted by default — not user (who you are), not feedback (how you like to be worked with), because neither belongs in a committed log. Anything matching a secret detector, or a term you list in sensitiveTerms, is quarantined rather than offered.

The ledger itself lives at katra/.state/memory-ledger.json and is deliberately local and gitignored — raw agent memory is unreviewed text about you and your machine, and it should never reach a shared branch by default; only the prose you choose to write from it does. So "review" means the katra memory scan | status | resolve | ignore queue *on the machine that produced it*: a teammate cloning the repo gets your entries, not your ledger.

Alternatives

Read this before adopting. Several tools do part of this, and some of them are a better fit than this one.

| Keep a Changelog + [release-please](https://gi