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.
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.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
