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.

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 — <task> 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   <task>   # 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 <slug> <ref> 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.