Quickstart

Install

npm install -g kadence

Node 20 or newer. The test suite runs on Linux in CI; the packed package is installed and run on Linux, macOS and Windows with npm, pnpm, yarn and bun — and without installing, through npx, pnpm dlx and bunx. Used daily on macOS. One runtime dependency (the terminal UI library), 141 KB packed. Upgrading is npm install -g kadence@latest; removing it is npm uninstall -g kadence, and your .kadence/ folder stays readable JSON either way.

npx kadence works for a single command, but it leaves nothing installed — the obvious next step then fails with "command not found". Install globally.

The first ten minutes

For whoever owns CLAUDE.md in the repository:

cd your-project
kadence init
kadence task add "Fix login" --type bug --priority high
kadence decision add "Keep sessions in Redis" \
  --why "Revocation must be instant" --rejected "JWT: cannot revoke before expiry"

In a terminal, kadence init walks you through it. Coda, the notehead on this page, says what it found — the agents already in the repository, an ADR folder — and asks one question with a recommended answer. Nothing is written before you answer. If the repository has ADRs, they are offered as decisions, each linked to its file, with a preview and a box to uncheck; if not, Coda asks for one decision by hand. Then it runs the prompt hook on what you just wrote and shows what a teammate's agent will see when someone proposes what you ruled out, gives you a line to send that teammate, and lists the files to commit — kadence never commits for you. Ctrl-C keeps whatever is already written; running init again is a checkup.

Any flag skips the questions, and so does an agent: run by Claude Code, Codex or Cursor, or in CI, init asks nothing and ends its output with what the agent should do next.

init creates .kadence/ and adds a short section to AGENTS.md and CLAUDE.md so your AI agents find the tool without being told about it — anything a human wrote in those files is left alone. It also adds two Claude Code hooks to .claude/settings.json: one runs kadence prime when a session starts, the other searches the journal on each prompt and puts up to three records next to it. Hooks already in that file are kept. kadence init --no-hooks leaves .claude/ untouched.

Open a new agent session. The hook runs kadence prime, and the agent starts knowing what is open, what is ready and the decision with its reason:

Nothing claimed by you.

Ready to start: 1  (kadence ready)

Decisions in force:
  DEC-1 Keep sessions in Redis

Go deeper:
  kadence search "…"         why, where, how — before grep
  kadence ready              what can be started now
  kadence task show KAD-1    one task in full, with its decisions
  kadence decision list      the reasons behind the work
  kadence board              the whole board

Ask it why sessions are in Redis. Before the agent reads the question, the prompt hook has already put the decision next to it:

kadence: if this is about why or how something was decided, the journal may already say:
  DEC-1  [decision] Keep sessions in Redis
         “Keep sessions in Redis Revocation must be instant JWT: cannot revoke before expiry”
More: kadence search "…" --json · open one: task show / decision show / doc show

It answers from the journal, not from a guess. The search is by words: a question that shares none with the record ("how should we store sessions?") gets nothing, and the hook says nothing rather than guess. Then commit what init wrote:

git add .kadence AGENTS.md CLAUDE.md .claude/settings.json .gitignore
git commit -m "Keep the team's work next to the code"

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

Adding a teammate

1. They install it: npm install -g kadence. Nothing is configured per person.
2. They pull. Their agent reads the same section in CLAUDE.md or AGENTS.md and, through the hook, runs kadence prime in its first session. On a machine where kadence is not installed yet, the hook prints one line asking the human for the install instead of failing — it does not reach for npx, because a hook in a shared repository must not download code on someone else's machine.
3. One identity per person. Authorship is git config user.email. The same person on two machines with two addresses reads as two people.
4. Agents say so. With KADENCE_SOURCE=agent in the agent's environment its writes carry [agent] next to the same email, so a person and their agent stay distinguishable.

kadence task show KAD-1 then lists their comment, note or move under their address. That second author is the moment the journal starts doing its job.

When several people work the same board

kadence ready                  # open, unblocked, nobody else's
kadence task claim             # take the top of that list, in one step
kadence note "Redirect drops the cookie, not the session" --task KAD-1
kadence task release KAD-1

There is no lock. Two machines can each claim before either pushes; the merge keeps both claims and the task reads contested with both names.

Look at the board

kadence board   # plain columns, for pipes and scripts
kadence ui      # interactive kanban in the terminal

kadence ui is keyboard and mouse driven, with drag between columns and every field editable in place. It calls the same commands the CLI does, so the two cannot disagree. It also loads lazily, so kadence task add never pays for it. Without a sprint its header reads 6 open · 2 ready · 1 decision in force; points appear only when something is estimated.

Read one piece of work

kadence task show KAD-1

Status, type, priority, blockers, estimate, logged hours, comments, and the full history of events that led there. Add --json and your AI agent reads the same thing.

Sprints and reports, if you want them

None of it is required, and none of it is the point — it is what the journal happens to know.

kadence sprint create "Sprint 14"
kadence task add "Token refresh" --estimate 3   # points only if you estimate
kadence sprint add KAD-2
kadence sprint close
kadence report --list                           # six reports, attention first
kadence report flow --html                      # one page, charts, no network

Closing a sprint prints what it cost, derived from the timestamps already in the journal — nobody fills in a form:

Sprint "Sprint 14" closed.

  Velocity:  23 of 28 points
  Actual:    37h — 1.6h per point

Removing kadence

Everything init touched, so you can undo it by hand:

Then npm uninstall -g kadence. Nothing lives outside the repository and your global node_modules.