Never explain the same decision twice.
Your coding agent has amnesia. You keep re-explaining decisions you already made —
and it keeps suggesting the thing you rejected in July. dira remembers why.
Website · Quick start · Commands · Releases · Example ledger
dira is decision memory for AI coding agents, stored in Git. It records what you chose, why you chose it, which alternatives you rejected, and what would make you reconsider. Claude Code hooks bring that context into new sessions and stage new decisions for review.
Each entry is a Markdown file with YAML frontmatter in .dira/entries/, committed
alongside your code. The CLI runs locally without an account, API key, or model
client. Semantic capture uses the coding agent already in your session.
dira is Swahili for compass.
Install with Homebrew:
brew install kazi-org/tap/dira
dira --versionOr download a binary for macOS or Linux (ARM64 or AMD64) from
GitHub Releases. Releases include
checksums.txt for verification. Linux ARM64 users should use the release archive;
the Homebrew formula covers macOS ARM64/AMD64 and Linux AMD64.
In the repository where you want to keep decisions:
dira init --interviewThe short interview seeds an intent, a constraint, and an open question. Choose
workspace for a project ledger. Then record a decision:
dira log --kind decision --title "Use SQLite for local storage" \
--alternative "PostgreSQL" \
--why-not "Local storage must work offline without a database server" \
--revisit-if "Multiple users need concurrent remote writes"
dira why SQLite
dira check "use PostgreSQL for local storage"why shows the decision and its reasoning. check reports the conflict, cites
the rejected alternative, and exits with code 2. Commit .dira/ with your code;
the derived cache is disposable.
With dira on your PATH, install the hooks and capture skill:
dira install-hooks
dira install-skillThese commands merge hooks into ~/.claude/settings.json and install the skill at
~/.claude/skills/dira/SKILL.md. Existing settings and hooks are preserved. Start
a new Claude Code session in your repository to receive the brief.
dira brief # Read the current focus, blockers, and recent decisions
dira distill # Review staged captures in an interactive terminal
dira ui # Browse the ledger in a local, read-only web viewThe CLI also works directly from your terminal or another agent's workflow. The bundled hooks and skill target Claude Code.
Release archives and checksums.txt are available from
GitHub Releases. For example, download
and verify the macOS ARM64 archive with Bash:
set -euo pipefail
VERSION=0.2.0 # Choose an existing release tag, without the leading v.
ASSET="dira_${VERSION}_darwin_arm64.tar.gz"
curl -fLO "https://github.com/kazi-org/dira/releases/download/v${VERSION}/${ASSET}"
curl -fLO "https://github.com/kazi-org/dira/releases/download/v${VERSION}/checksums.txt"
grep " ${ASSET}$" checksums.txt | shasum -a 256 -c -
tar -xzf "${ASSET}"
./dira --versionFor an Intel Mac, use dira_${VERSION}_darwin_amd64.tar.gz; for Linux AMD64,
use dira_${VERSION}_linux_amd64.tar.gz; for Linux ARM64, use
dira_${VERSION}_linux_arm64.tar.gz. On Linux, sha256sum -c - can replace
shasum -a 256 -c -. Put the verified dira executable in a directory on your
PATH to use it outside the download directory.
Capture → review → recall → check. dira keeps the reasoning close to the code and makes it available when the next decision is being made.
The installed hooks run at three points:
| Claude Code event | Command | Purpose |
|---|---|---|
SessionStart |
dira brief --context --chain |
Supply decision context before work begins. |
Stop |
dira sniff --stage --quiet |
Stage candidate decisions from the session transcript. |
PreCompact |
dira sniff --deep --stage --all |
Capture candidates before the transcript is compacted. |
sniff uses regular expressions. It stages candidates; it does not invent reasons
or accept decisions. In dira distill, you can confirm, ignore, edit, or undo.
Confirming a capture marks it for semantic extraction and leaves it staged until
its reasoning is supplied. The capture skill lets the session agent fill in that
reasoning from the conversation.
The PreCompact hook preserves candidates, but its output alone does not guarantee
that the agent completes semantic extraction. Review pending captures with
dira distill. See the hook configuration for the
exact commands and delivery constraints.
dira brief summarizes blockers, active intents, and recent decisions in at most
1,500 tokens. dira why QUERY follows an entry's reasoning chain, including rejected
alternatives and the conditions that would reopen them.
Run a proposed plan through dira check before implementing it. For example,
inside this repository:
dira check "rewrite dira in Elixir using OTP"The ledger cites dec-0001, which records the choice of Go and the reasons for
rejecting Elixir/OTP. Matching is lexical and offline: it detects matches to
recorded rejected alternatives, not every possible semantic contradiction. A
clean result means no conflict was detected by that matcher.
For check, exit 0 means no conflict, 2 means a conflict, and 1 means the
check failed to run, including invalid arguments. Use these codes in your own
planning workflow; the installed capture hooks do not automatically gate plans.
Other commands generally use 2 for usage errors; consult dira help COMMAND.
When circumstances change, record the replacement decision and link it explicitly:
dira supersede dec-0001 --with dec-0002 --note "Requirements have changed"Use the IDs from your own ledger. Superseding preserves the history, retires the
old entry, and makes the replacement the decision check consults.
| Command | Purpose |
|---|---|
init |
Seed a ledger through a short interview. |
log |
Write an entry or add a relationship to an existing one. |
sniff |
Stage candidate decisions from a session transcript. |
distill |
Review staged captures interactively. |
brief |
Summarize blockers, focus, and recent decisions. |
why |
Show the reasoning behind an entry and its rejected alternatives. |
check |
Check a plan against settled decisions. |
map |
Group intents and decisions, with execution status from kazi when available. |
supersede |
Replace a settled entry while preserving its history. |
ui |
Serve a read-only ledger browser on localhost. |
import |
Measure existing ADRs and offer to import or index them. |
install-hooks |
Merge Claude Code hook registrations into settings. |
install-skill |
Install the Claude Code capture skill. |
reindex |
Rebuild the derived SQLite cache from entry files. |
version |
Print the binary version. |
This table describes the current source tree; an installed release may have fewer
commands. Run dira --help or dira help COMMAND for your binary's options.
dira import docs/adrImport scans the directory and reports how many documents contain a rejected
option with a reason. It asks before writing; --yes confirms noninteractively.
Imported decisions are staged for review, with source filenames and content hashes.
If no document contains a reasoned rejection, dira offers to index the documents in its cache instead. It does not manufacture rejected alternatives to make an ADR look enforceable.
.dira/
├── config.toml # Ledger configuration
├── entries/ # Version-controlled Markdown with YAML frontmatter
│ ├── int-0001.md
│ └── dec-0001.md
└── cache/ # Derived SQLite cache; rebuild with dira reindex
The five entry kinds are intent, decision, question, constraint, and note.
Rejected alternatives belong to a decision, with a reason and an optional
revisit_if condition. Relationships connect entries into a reasoning chain.
You can read, diff, and review the files with ordinary Git tools. The cache is rebuildable from those files. Browse this repository's ledger for real examples, or consult the entry schema.
Parent ledgers declared in .dira/config.toml let you organize personal, workspace,
and repository context. dira brief --chain surfaces parent context; namespaced
references connect entries across ledgers. See the design document
for the tier model and privacy rules.
The ledger model, its codec, the frontmatter splitter, and the entry schema
are importable packages, so a tool that reads or writes .dira/ does not have
to copy dira's sources or shell out to the CLI:
import (
"github.com/kazi-org/dira/frontmatter" // split an entry file into YAML + body
"github.com/kazi-org/dira/ledger" // Entry, Decode, Encode, Validate, Store
"github.com/kazi-org/dira/ledger/local" // the filesystem-backed Store
"github.com/kazi-org/dira/schema" // the JSON Schema and its validator
)ledger/fixture and ledger/ledgertest are test helpers and are public for
the same reason. Everything under internal/ remains dira's own and may
change without notice; the packages above follow the module's semver tags.
kazi checks whether a declared goal is complete. dira preserves why that goal matters and which choices led to it. Both work independently.
dira map groups active intents and accepted decisions and reads execution status
through kazi's public JSON interface. If kazi is unavailable, the ledger groups
still render and dira explains why execution status is missing. Execution status
is derived at read time, never stored in the ledger.
Use the Go version specified in go.mod:
git clone https://github.com/kazi-org/dira.git
cd dira
go build ./cmd/dira
./dira --helpA source build reports dev; release builds embed their version at link time.
Before contributing, install the repository's pre-commit gates and run the tests:
sh hooks/install.sh
go test ./...The suite includes validation of this repository's ledger against the entry schema. See the design, roadmap, and work plan for architecture and ongoing work. Report bugs or suggest improvements through GitHub Issues.
Capture, review, conflict checks, ADR import, and a read-only ledger browser are available in dira. See releases for versioned changes.
Apache License 2.0. See NOTICE for attribution.