work that survives the session
Your team and your AI agents, working from the same context.
Tasks, their history and the reasoning behind them, as an append-only journal in your git repo. The next session — human or AI agent — starts where the last one stopped.
For repositories where more than one person — or more than one AI agent — works on the same code.
then run kadence init — 60-second quickstart →
KAD-1 Fix login redirect Session cookie dropped on redirect Status: in_review Type: bug Priority: high Blocked by: KAD-7 Estimate: 3 Logged: 4.5h
- 09-01 10:02anatask.created
- 09-01 14:40anatask.moved → in_progress
- 09-02 09:14anatask.commented
- 09-02 09:20agenttask.blocked_by_added
- 09-02 11:05agenttask.moved → in_review
Five events, two authors, one of them an AI agent — the whole state of one piece of work, printed by the real binary. --json gives your agent the same thing.
demo
Forty seconds, from empty repo to a number.
Your code says what. Git says when. Nothing says why.
before
An approach is tried and dropped, a decision is made in a thread. Two weeks later the only trace is a diff that does not explain itself.
the cost
A person loses minutes. An AI agent loses the session: it re-reads the same files and asks the question you answered yesterday.
after
kadence keeps that layer as events, committed with the code. One call returns a piece of work whole — and every step that led there.
Everyone keeps work in the repo now. Almost everyone keeps state.
State drifts.
A file edited on Thursday no longer says what happened Monday. An event records that something occurred — it cannot drift.
State conflicts.
One task edited on two branches is a merge conflict in every file-based tracker. Here it is not: one file per event, never rewritten.
State forgets.
Rewriting a file destroys the previous version. The journal keeps every step, so how-did-we-get-here has an answer.
State is folded from the journal on read, so the board can never drift from reality.
The change is in git. The reason it was made is nowhere.
Nobody records what was tried and thrown away — so the next session proposes it again.
$ kadence decision add "Store sessions in a signed cookie" \
--why "The redirect drops server-side session state" \
--rejected "Server-side sessions: they break on redirect" \
--task KAD-1
DEC-1 recorded.
$ kadence decision add "Signed cookie, rotated hourly" \
--why "A stolen cookie stayed valid for a week" \
--supersedes DEC-1
DEC-2 recorded.
It replaces DEC-1, and both links were written by one event — neither side can go stale.
$ kadence decision list
DEC-2 Signed cookie, rotated hourly- 01Why is a required field.
decision add refuses a record without --why. What changed is a changelog line, and git already has one.
- 02Superseding is one event, not two edits.
--supersedes writes one record; the backward link is derived on read. Two edits in a file, and one side gets forgotten — so a reversed decision keeps looking current.
- 03What you get back is what still holds.
decision list returns what is in force; --all adds history. An agent quoting a reversed reason is worse than one with no memory.
kadence task doc KAD-1 docs/design.md links the document that explains the work. git versions the file; kadence records the one thing git cannot — that it belongs to this task.
Why the merge claim holds
We measured it before building on it — first in other people's repositories, then in ours.
merge commits across 130 public repositories using file-based trackers
of those repositories hit conflicts in task files
are CONFLICT (content) — the type an append-only journal removes
conflicts when three people edit one task on three branches, merged in every order
The last one is an integration test — three people editing one task on three branches, merged in every order. Not a claim. Full data →
How it works
- 1kadence init — one folder, .kadence/, committed with your code.
- 2Every command appends one event. Move a task, log an hour, close a sprint — one file each, never edited, never deleted.
- 3State is folded from the journal on read. The board cannot drift from reality, and velocity is not a field someone maintains.
.kadence/
|- state.json derived cache
`- events/
|- archive/ one file per month
`- 2026-09/ one file per eventBecause every event is timestamped, the cost of the work falls out of the same journal — nobody logs it by hand.
$ kadence sprint close Sprint "Sprint 14" closed. Velocity: 23 of 28 points Actual: 37h — 1.6h per point Carried over (2): · KAD-12 Auth refactor
What it costs you
- Install
- 44 KB · packed — 131 KB of kadence, plus 1.8 MB of blessed
- Startup
- 80 ms
- 10,000 events
- 28 ms cold · 7 ms warm
- Journal on disk
- 1.9 MB
- One task, as an AI agent reads it
- 948 bytes · the same at 10 tasks or 1,000
- Licence
- MIT
These are tests. They fail the build on regression, which is why they are still true.
Files first. The contract is published, not promised.
everyone else
Three hops, a token, and a network that has to be up.
kadence
One hop. It is a folder — your AI agent already knows how to read it.
Every command speaks --json; a failure carries a code and the allowed set. init writes the guide into AGENTS.md and CLAUDE.md — the file Claude Code actually loads.
$ kadence task show KAD-1 --json
{"schema":"kadence/v1","ok":true,"task":{
"label":"KAD-1","status":"in_review","estimate":3,
"loggedHours":4.5,"blockedBy":["01M1PN2NVGQFD…"],
"comments":[{"author":"ana","ts":"2026-09-02T09:14:00Z",
"text":"The redirect drops the cookie, not the session."}],
"history":[
{"type":"task.created","actor":"ana",
"ts":"2026-09-01T10:02:00Z"},
{"type":"task.moved","actor":"ana",
"ts":"2026-09-01T14:40:00Z",
"data":{"from":"backlog","to":"in_progress"}},
{"type":"task.blocked_by_added","actor":"agent",
"ts":"2026-09-02T09:20:00Z"}
]}}One task is 948 bytes at ten tasks or a thousand, while the journal behind it grows 5 KB → 528 KB. MCP stays optional: measured at ~700 tokens a session.
$ kadence schema --json
$ kadence task show KAD-1 --json
$ kadence board --json \
--fields label,status,assignee
$ KADENCE_SOURCE=agent \
kadence task move KAD-1 in_progressWhat we have proved, and what we have not
Verified
The merge thesis, on real branches. Size and speed, by tests that fail the build. 548 tests.
Not verified
That teams lose enough context to want this. The bet rests on reasoning, not on users — the interviews are not yet run.
On the roadmap, not shipped
context --branch: the work behind your branch in one call. An optional MCP package. Two ideas dropped after measurement: context <task> and kadence doc.
Known limits
Conflicts are real but rare — one merge in two hundred — so they are our proof, not our headline. The terminal UI is tested by hand.
We have not talked to enough teams.
One question we cannot answer alone: what your team loses when an AI agent picks the work back up. Thirty minutes is worth more to us than a star. No pitch — we ask, you talk.
Book thirty minutes →Questions people ask first
Is this another tracker? We use Jira.
No. It keeps the layer Jira has no place for — what actually happened to a piece of work, in a form your AI agent can read. They live side by side.
My AI agent already reads the repo. What does this add?
The repo says what the code is, not what was tried, rejected or blocked and why. kadence decision records that next to the work — and marks it superseded when it stops being true.
Does my agent need an MCP server?
No. It reads a folder and runs a command. init writes the guide into AGENTS.md and CLAUDE.md; kadence schema --json publishes the whole contract. MCP is optional and not shipped.
What does it do to my repository?
It creates .kadence/ and appends files to it, and adds a short section to AGENTS.md and CLAUDE.md so your agents find it — whatever a human wrote in those files is left alone. It edits nothing else, deletes nothing, and runs no git command on your behalf.
Can anyone else see our work?
No. The CLI has no network code and no telemetry at all — turn off your wifi and check. This site counts anonymous page views and four things a visitor can do here (copy the install command, play the demo, star it on GitHub, book a call). No cookies, no local storage, no session recording, and Do Not Track is honoured.
What if we change our mind?
rm -rf .kadence. The events are plain JSON, so your history stays readable without kadence.
start here
then run kadence init
Sprint "Sprint 14" closed. Velocity: 23 of 28 points Actual: 37h — 1.6h per point