kizami — A minimal CLI tool to maintain living documentation alongside code, with automatic drift detection.
Design decisions tend to get scattered across Issues, PRs, and Slack — and eventually lost.
kizami saves them as Markdown files alongside your code, so the reasoning behind every choice is recorded and kept accurate over time.
$ kizami adr "use PostgreSQL over SQLite"
Created: docs/decisions/2026-03-12-use-postgresql-over-sqlite.md
$ kizami list
Slug Date Status Title
---- ---- ------ -----
use-postgresql-over-sqlite 2026-03-12 Draft use PostgreSQL over SQLite
command-name-kizami 2026-03-12 Active Command name "kizami"
...
$ kizami search "PostgreSQL"
docs/decisions/2026-03-12-use-postgresql-over-sqlite.md:1: # use PostgreSQL over SQLite
Full documentation is available at mskasa.github.io/kizami — workflow guides, ADR writing tips, configuration reference, and more.
go install github.com/mskasa/kizami@latestDownload the latest binary for your platform from the Releases page.
macOS / Linux
# macOS (Apple Silicon)
curl -L https://github.com/mskasa/kizami/releases/latest/download/kizami_darwin_arm64.tar.gz | tar xz
mv kizami /usr/local/bin/
# macOS (Intel)
curl -L https://github.com/mskasa/kizami/releases/latest/download/kizami_darwin_amd64.tar.gz | tar xz
mv kizami /usr/local/bin/
# Linux (amd64)
curl -L https://github.com/mskasa/kizami/releases/latest/download/kizami_linux_amd64.tar.gz | tar xz
mv kizami /usr/local/bin/Windows (PowerShell, requires administrator)
# amd64
Invoke-WebRequest -Uri https://github.com/mskasa/kizami/releases/latest/download/kizami_windows_amd64.zip -OutFile kizami.zip
Expand-Archive kizami.zip -DestinationPath kizami_bin
Move-Item kizami_bin\kizami.exe C:\Windows\System32\kizami.exe
Remove-Item kizami.zip, kizami_bin -Recurse# 1. Initialize your decisions directory
kizami init
# 2. Record an architectural decision (ADR)
kizami adr "use PostgreSQL over SQLite"
# Opens the generated Markdown file in your $EDITOR
# 2b. Create a design document
kizami design "connection pool design"
# 3. List all decisions
kizami list
# 4. View a specific decision
kizami show use-postgresql-over-sqlite
# 5. Search by keyword
kizami search "PostgreSQL"
# 6. Update a status
kizami status use-postgresql-over-sqlite inactive
kizami status use-sqlite superseded --by use-postgresql-over-sqliteInstead of asking a senior engineer "why is the code structured this way?", new members can look it up themselves.
$ kizami list
Slug Date Status Title
---- ---- ------ -----
use-postgresql-over-sqlite 2025-09-01 Active Use PostgreSQL over SQLite
auth-jwt-strategy 2025-10-15 Active Auth JWT strategy
connection-pool-design 2025-11-20 Active Connection pool design
...
$ kizami show use-postgresql-over-sqlite
# Use PostgreSQL over SQLite
- Date: 2025-09-01
- Status: Active
## Context
Load tests at 500 concurrent users revealed SQLite's write lock as a bottleneck.
## Decision
Switch to PostgreSQL. Accepted the operational overhead in exchange for write scalability.Even a new team member can understand the reasoning behind past decisions right alongside the code.
When a reviewer asks about a design choice, point to the ADR instead of re-explaining from scratch.
$ kizami blame internal/db/db.go
docs/decisions/2025-09-01-use-postgresql-over-sqlite.mdReviewers get the context instantly, and discussions stay focused on what matters.
kizami review surfaces documents that haven't been updated in a long time, so outdated docs don't get quietly ignored.
$ kizami review
docs/decisions/2025-08-20-redis-caching-strategy.md
Last updated 9 months ago — worth revisiting?Because decisions are stored as plain Markdown files, you can feed past decisions directly to an AI assistant.
$ kizami show use-postgresql-over-sqlite
# Use PostgreSQL over SQLite
- Status: Active
## Context
Load tests at 500 concurrent users revealed SQLite's write lock as a bottleneck.
## Decision
Switch to PostgreSQL. Accepted the operational overhead in exchange for write scalability.Pass this to your AI assistant and it can make suggestions that respect your existing constraints and trade-offs — no need to re-explain the background every time.
| Command | Description |
|---|---|
kizami init |
Initialize the decisions directory and optional GitHub Actions workflows |
kizami adr "<title>" |
Create a new ADR and open it in $EDITOR |
kizami design "<title>" |
Create a new design document and open it in $EDITOR |
kizami list |
List all documents in reverse chronological order |
kizami show <slug> |
Print the full content of a document |
kizami search <keyword> |
Search documents by keyword |
kizami status <slug> <status> |
Update the status of a document |
kizami supersede <slug> "<title>" |
Supersede an existing document and create a new one |
kizami blame <file> |
Find documents that reference a given file |
kizami audit |
Detect drift between Related Files sections and actual code |
kizami lint |
Validate document structure for CI |
kizami review |
Detect long-stale documents |
| Status | Meaning |
|---|---|
Active |
Currently valid decision (default) |
Inactive |
No longer applicable, no replacement |
Superseded by <slug> |
Replaced by another document |
kizami status use-sqlite inactive
kizami status use-sqlite superseded --by use-postgresql-over-sqliteDecisions are saved as Markdown files under docs/decisions/ using a MADR-compatible template:
docs/decisions/
├── 2026-03-12-use-go-over-shell-script.md
├── 2026-03-12-use-cobra-for-cli-framework.md
└── ...
File naming: YYYY-MM-DD-kebab-case-title.md
# Use PostgreSQL over SQLite
- Date: 2026-03-12
- Status: Active
- Author: you
## Context
<!-- Why this decision was needed -->
## Decision
<!-- What was decided -->
## Consequences
<!-- Impact, benefits, trade-offs -->
## Alternatives Considered
<!-- Options not adopted, and why -->
## Related Files
<!-- List files related to this decision (e.g. internal/db/db.go) -->The ## Related Files section links any document to the source files it references.
kizami audit detects when those files are deleted or moved — keeping documentation honest.
kizami audit
# Checks all Related Files entries in docs/decisions/ and reports missing fileskizami search uses ripgrep when available for speed, and falls back to a pure Go implementation when it is not installed — so it works everywhere.
This repository uses kizami to record its own design decisions. Browse docs/decisions/ to see it in action.
MIT