Your first decision
A complete walkthrough: create a ledger, record a choice, check a plan, and change direction.
Open source · Reasoning kept in Git
Never explain
the same
decision twice.
Keep the why behind your code. dira records decisions and rejected alternatives in your repo, brings them into your coding agent's next session, and checks proposed work against what you already decided.
brew install kazi-org/tap/diraLocal CLI. Plain files. No Dira account.
Decision“Use Go for dira's CLI.”
Rejected alternative“Elixir / OTP”
Reason“dira runs in the path of a human waiting for a prompt. Process startup matters.”
Revisit if“dira grows a genuinely long-lived component.”
Adapted from dira's own ledger · view the actual record
dira check "rewrite dira in Elixir using OTP"
Conflict found: dec-0001
This proposal matches a rejected alternative. Review the recorded reason, revise the plan, or explicitly supersede the decision.
Illustrative rendering of the documented check. Matching is lexical.
01 / Continuity
The reasoning survives the session.
Capture the decision, bring it back when work resumes, and consult it before repeating an old argument.
01
Capture candidates
Claude Code hooks stage possible decisions from the conversation. You review the captures; the session's skill supplies the reasoning.
sniff · distill02
Start with context
A session-start brief brings blockers, active intentions, and recent decisions into context, capped at 1,500 tokens.
brief03
Check before proceeding
Check a proposed plan against recorded decisions. When direction changes, explicitly supersede the old record.
check · supersede02 / The Record
A choice is only half the story.
Keep the alternative, the reason it lost, and the condition that would make it worth considering again.
Below is the same example record from dira's ledger. Selecting a part changes emphasis only — the full record stays visible.
Decision“Use Go for dira's CLI.”
Rejected alternative“Elixir / OTP” — process startup matters for a short-lived CLI in the prompt’s latency path.
Revisit if“dira grows a genuinely long-lived component.”
A rejected alternative carries a reason, so a later session can examine the argument that settled it.
03 / Your Repository
The record lives with the work.
.dira/config.tomlconfiguration
.dira/entries/int-0001.mdan intent
.dira/entries/dec-0001.mda decision
.dira/cache/derived, rebuildable data
Each entry is Markdown with YAML frontmatter. Commit it alongside your code. Review it in a diff. The files remain readable even without dira.
Already have ADRs?
Run dira import DIR to inspect what your documents contain before importing. Reasoned rejections become staged entries after confirmation; documents without them can be indexed instead.
Using kazi?
dira keeps the reasoning behind a goal. kazi checks whether the work satisfies its acceptance predicates. Use either independently, or keep direction and execution connected.
04 / Installation
Give the next session a starting point.
1
Install the CLI
brew install kazi-org/tap/dira dira --version
Homebrew support is documented for Apple Silicon Macs, Intel Macs, and Linux amd64. For other published builds, use the release archives.
2
Initialize your project
From your project directory, answer a short interview. Choose workspace to seed an intent, a constraint, and an open question:
dira init --interview
3
Connect Claude Code
dira install-hooks dira install-skill
These commands add dira's hooks and capture skill to your Claude Code configuration. Start a new session after setup.
05 / Questions
Straight answers.
Does dira require a hosted service?
No. The CLI and ledger work locally without a Dira account. The optional web viewer runs on your machine.
Does it call an AI model?
The binary has no model client. Its semantic capture skill uses the coding-agent session you already have running.
Will it catch every contradiction?
No. dira check uses lexical matching against recorded decisions. It provides a concrete check with cited reasoning, not a guarantee of complete semantic detection.
Does confirming a capture accept the decision?
No. Confirmation marks the capture for semantic extraction; it stays staged until its reasoning is supplied. The agent must complete that step. Read the capture workflow.
06 / Go further
Follow the reasoning.
The command reference
Every command and its flags, generated from the actual CLI at build time.
Dira’s own ledger
Explore the real intents, constraints, and decisions behind the project you’re looking at.