kadence weekly downloads statistics

kadence

Your team and your AI agents work from the same context — it lives in your repo and remembers what the code cannot.

No server. No account. No network. Tasks, their whole history and the time they took are files next to your code, and they move with your branches.

The context your code cannot hold

Your code says what exists. git log says when it changed. Neither says what was tried and abandoned, why a task is blocked, or what the team agreed on Tuesday.

That gap costs a human a few minutes. It costs an AI agent the entire session: every new one starts from scratch, re-reads the same files and asks the same questions you answered yesterday.

kadence keeps that missing layer as an append-only journal — one file per event, committed with the code:

That is the whole state of a piece of work, in one call, with no server to ask and no context to rebuild. A human reads it in kadence task show. An AI agent reads the same thing as JSON.

And it stays one call. That answer stays under a kilobyte whether the project holds ten tasks or a thousand — while the journal behind it grows from 5 KB to 528 KB. The cost of asking does not grow with the history that makes the answer worth having. Measured at 948 bytes in 0.2; 982 bytes at 0.4, after claims and acceptance criteria joined every record.

Why events and not files

Every other tool that keeps work in a repository keeps state: a task file, a row in a database, the current spec. State has three failure modes, and all three are why kadence stores events instead.

It drifts. A spec written on Monday and edited by an agent on Thursday no longer says what actually happened. An event cannot drift — it records that something occurred, not what is currently true.

It conflicts. Two people editing one task on two branches is a merge conflict in every file-based tracker. Here it is not, by construction: the journal is append-only, one file per event.

It forgets. Rewriting a task file destroys the previous version. The journal keeps every step, so «how did we get here» has an answer.

State is still there when you want it — it is folded from the journal on read, which is why the board cannot drift from the journal. No one maintains a column by hand, so no column can be stale in the way a task file can.

What that does not buy you. A journal records what was written to it. If a piece of work stops being touched, the board stays perfectly accurate and perfectly uninformative about it — the same way git log is honest about a branch nobody pushed to. kadence removes the drift between what is shown and what was recorded. It cannot remove the drift between what was recorded and what is actually happening; that still takes someone looking.

Why the merge claim holds

We measured it before building on it.

Across 8,396 merge commits in 130 public repositories using file-based trackers, conflicts in task files hit 15% of repositories — and **89% are CONFLICT (content)**, the exact type an append-only journal removes.

Then the other direction: three people editing one task on three branches, merged in every order. Zero conflicts, every author preserved, identical final state. That is an integration test, not a claim.

The measurement itself is a working paper and is not published (see .gitignore); the mechanism it measures is proved here by test/integration/merge.test.ts.

And for agents running side by side, which is where neighbouring tools lose work: **eight processes writing 200 tasks into one working tree at once, and three worktrees writing 240 more and merged in one octopus merge — no conflict, no task lost**; two worktrees claiming the same task come out of the merge with one claim and the other reported as contested, not silently dropped. Every agent writes its own file, so there is nothing to overwrite. The proof is test/parallel-agents.test.ts — it runs the real binary in separate processes, and fails (182 of 200) when the store is made to share file names.

In practice

The first ten minutes, for the person who owns CLAUDE.md:

Run in a terminal, kadence init is a guided setup: Coda says what it found — the agents in use, an ADR folder — asks one question with a recommended answer, offers the ADRs as decisions, and shows what a teammate's agent will see when someone proposes what you ruled out. Nothing is written until you say so, and running it again is a checkup. An agent, a script or any flag gets no question at all, and the output tells an agent what to do next.

On Codex, Cursor or Copilot, kadence init --hooks-for codex,cursor,copilot adds their hooks too; init writes them unasked only where the agent's own directory is already in the repository.

Open a new agent session. The hook runs kadence prime, and the agent starts knowing what is open, what is ready and DEC-1 with its reason — ask it how sessions should be stored and it answers from the journal, not from a guess.

kadence never commits for you. Once that commit is pushed, the journal is the team's, not yours.

If the repository is public, add the topic kadence-journal to it (the gear next to *About* on GitHub, or gh repo edit --add-topic kadence-journal). kadence sends nothing anywhere, so a topic you choose to show is the only way anyone, us included, can tell it is in use.

Adding a teammate…

Description from the npm listing.