katra

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/lockup-dark.svg">
    <img src="docs/assets/brand/lockup.svg" alt="katra" width="408" height="91">
  </picture>
</p>

# katra

[![CI](https://github.com/craigjmidwinter/katra/actions/workflows/ci.yml/badge.svg)](https://github.com/craigjmidwinter/katra/actions/workflows/ci.yml)
[![Go Reference](https://pkg.go.dev/badge/github.com/craigjmidwinter/katra.svg)](https://pkg.go.dev/github.com/craigjmidwinter/katra)
[![Go version](https://img.shields.io/github/go-mod/go-version/craigjmidwinter/katra)](go.mod)
[![Release](https://img.shields.io/github/v/release/craigjmidwinter/katra?color=blue)](https://github.com/craigjmidwinter/katra/releases/latest)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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](#the-agent-workflow) below.

```bash
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

![The Overview page: a Future → Now → Past spine down the middle, the current draft sitting at Now awaiting a stamp, and load-bearing choices and threads pulled into the right rail](docs/assets/screenshots/viewer-overview.png)

`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.

<details>
<summary>More screenshots</summary>

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

![An in-progress entry with a before/after slider comparing two versions of the page-fold icon mark, and a table of contents generated from the entry's own headings](docs/assets/screenshots/viewer-entry.png)

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 Board view with tasks grouped into todo, specced, doing and done columns, one task sitting in doing with a link to its committed spec](docs/assets/screenshots/viewer-board.png)

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 hub's cross-project view: a grid of in-flight tasks and draft entries pulled from 14 separate repositories, each card labelled with its own project](docs/assets/screenshots/hub-projects.png)

</details>

## 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](docs/workflow.md): 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.

```bash
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`):

```bash
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](docs/workflow.md)
and [Agents](docs/agents.md).

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.*

```bash
katra task new "Cache swap"                           # todo, slug: cache-swap
katra decide "Cache invalidation: TTL, not events"   # write the design
katra task spec cache-swap