kal init
Create a kal repository. Adds a hidden .kal/; your files are untouched — and it coexists with an existing .git.
$ kal init initialized empty kal repository in /work/payments/.kal
Reference
Every command, and what it prints
Six themed groups instead of an alphabetical wall. Every example below is real output captured from kal 0.7.0 — nothing is mocked.
Start here
7Five commands and you are productive.
kal snap
Record everything, in one step. -m says what changed; -i records the intent — the why git never captures. --agent/--model attribute AI work.
$ kal snap -m "scaffold service" -i "starting the payments service" snap 70b33dfef289 scaffold service when 2026-07-26 02:18:16 author dev [human] intent starting the payments service files 2 added
kal status
What changed since the last snapshot. Uses a stat cache, so it stays instant in huge repos.
$ kal status on branch main M app.py
kal log
History with intents, authors (human or model) and file counts.
$ kal log snap 33223d8c4ba1 checkpoint when 2026-07-26 02:18:16 author dev [human] intent automatic work-in-progress checkpoint files 1 modified snap e8c7405a0044 add retry helper when 2026-07-26 02:18:16 author claude-code [ai:claude-opus-5] intent the IdP rate-limits bursts of logins files 1 modified snap 70b33dfef289 scaffold service when 2026-07-26 02:18:16 author dev [human] intent starting the payments service files 2 added
kal diff
Line-by-line changes against any snapshot.
$ kal diff --- a/app.py +++ b/app.py @@ -3,3 +3,4 @@ def retry(n=3): return n +# tuned
kal show
One snapshot in full — files, trust tier, and attached notes.
$ kal show HEAD snap 33223d8c4ba1 checkpoint when 2026-07-26 02:18:16 author dev [human] trust human-authored intent automatic work-in-progress checkpoint files 1 modified M app.py note [verification] 2026-07-26 02:18:16 by dev [human]: {"command": "\"python3\" -c \"raise SystemExit(0)\"", "exit_code": 0, "output_tail"
kal awards
Your journey: achievements and streaks that reward writing intents and verifying work.
$ kal awards Your kal journey 5/16 achievements 🌱 First Light earned your first snapshot in this repo 🔟 Ten Up █████░░░░░░░░░ 4/10 10 snapshots recorded 💯 Centurion ░░░░░░░░░░░░░░ 4/100 100 snapshots recorded ✍️ Why-Writer ████░░░░░░░░░░ 3/10 10 snapshots with an intent — history that explains itself 📖 Storyteller ████░░░░░░░░░░ 3/10 10 snaps in a row with intents ✅ Green Keeper █░░░░░░░░░░░░░ 1/10 10 passing verifications 🟢 On a Roll ██░░░░░░░░░░░░ 1/5 5 passing verifications in a row 🤝 Smooth Operator ██░░░░░░░░░░░░ 1/5 5 merges without a single conflict 🧵 Conflict Tamer ░░░░░░░░░░░░░░ 0/1 resolved a conflicted merge ⏪ Time Traveler earned used undo — nothing is ever lost in kal 🔍 Detective ░░░░░░░░░░░░░░ 0/1 found a culprit with bisect 🏺 Archaeologist ██░░░░░░░░░░░░ 2/10 asked your history 10 questions (why / ask) 🌉 Bridge Builder earned synced with git — best of both worlds 🚀 Team Player ░░░░░░░░░░░░░░ 0/1 first push to a remote 🗄️ Keeper of Lessons earned archived a branch with its lesson 🏷️ Release Captain earned tagged a release Live streaks: intents 0 · green verifies 1 (celebrations off: kal config ui.celebrations off)
Branch & combine
5Branches are free; merging is line-level smart.
kal branch
List, create, delete (-d) or rename (-m). Deleting unmerged work suggests kal archive instead — keep the lesson.
$ kal branch feature 72d109c8e852 * main e2bd12335d35
kal switch
Move between branches; refuses to trample uncommitted work unless forced.
$ kal switch feature switched to branch feature switched to branch main
kal merge
Real three-way, line-level merge. Different lines of the same file merge cleanly; genuine conflicts get minimal markers around just the disputed lines.
$ kal merge feature merged feature -> 8cc7226d95ba (merge feature)
kal tag
Name a snapshot. Tags work anywhere a revision is accepted — kal cat v1.0 app.py.
$ kal tag v1.0 tagged 8cc7226d95ba as v1.0 v1.0 8cc7226d95ba
kal restore
Bring back any file, or everything, from any snapshot.
$ kal restore HEAD app.py restored 1 file(s) from HEAD
Your safety net
8Every operation is recorded — and reversible.
kal undo
Undo the last operation: a snap, a merge, a reset, a branch delete. Snapshots are never destroyed, so undo is itself undoable.
$ kal undo undid operation #12 (tag: v1.0 at 8cc7226d95ba) refs restored to their prior state; commits are retained (undo is undoable) worktree files were left untouched — add --files to also reset them, or run `kal restore HEAD` yourself
kal ops
The operation log behind undo — every mutation with its before/after state.
$ kal ops #13 2026-07-26 02:18:18 undo undo #12 (tag) #12 2026-07-26 02:18:17 tag v1.0 at 8cc7226d95ba #11 2026-07-26 02:18:17 switch to main #10 2026-07-26 02:18:17 switch to feature #9 2026-07-26 02:18:17 merge feature #8 2026-07-26 02:18:17 snap friendlier greeting #7 2026-07-26 02:18:17 switch to main #6 2026-07-26 02:18:17 snap feature docs #5 2026-07-26 02:18:17 switch to feature …
kal checkpoint
A zero-thought snapshot for work in progress; content-addressing makes it nearly free.
$ kal checkpoint checkpoint 33223d8c4ba1 recorded (1 files)
kal revert
Create a new snapshot that undoes an old one — history preserved, mistake neutralised.
$ kal revert HEAD kal: revert of a merge commit is not supported yet
kal reset
Move the branch pointer anywhere. Frightening in git; calm here, because kal undo reverses it.
$ kal reset HEAD~1 reset main to 9f31c02ab8e1 — soft (worktree untouched); `kal undo` reverses this
kal bisect
Give it a good revision, a bad one and a test command; it binary-searches history for the exact snapshot that broke things — validating both endpoints first, so it cannot lie to you.
$ kal bisect a055e5116e63 HEAD --run "pytest" first bad snapshot: 1fe362ab798a refactor marker handling author dev [human] found in 4 test runs over a span of 3 snapshots
kal fsck
Verify every object hash and the reachability of history.
$ kal fsck objects checked : 18 reachable : 18 dangling : 0 (unreachable but intact — kept for undo) integrity: OK
kal gc
Prune only what no ref and no past operation can reach — GC that cannot break undo.
$ kal gc --dry-run reachable objects (refs + full oplog history): 18 would prune: 0 objects (0 bytes) note: kal gc is conservative — anything an undo could ever need is kept
Understand your code
10The commands git cannot have, because git does not know who wrote what, or why.
kal why
The provenance trail of a file: every snapshot that touched it, each with its intent.
$ kal why app.py provenance of app.py (newest first): snap 33223d8c4ba1 checkpoint when 2026-07-26 02:18:16 author dev [human] intent automatic work-in-progress checkpoint files 1 modified snap e8c7405a0044 add retry helper when 2026-07-26 02:18:16 author claude-code [ai:claude-opus-5] intent the IdP rate-limits bursts of logins files 1 modified snap 70b33dfef289 scaffold service when 2026-07-26 02:18:16 author dev [human] intent starting the payments service files 2 added
kal blame
Per-line attribution — and whether a human or an AI wrote each line, with the model name and a summary.
$ kal blame app.py 70b33dfe dev [hum] 1| def hello(): 70b33dfe dev [hum] 2| return 'hi' e8c7405a claude-code [ai] 3| e8c7405a claude-code [ai] 4| def retry(n=3): e8c7405a claude-code [ai] 5| return n 33223d8c dev [hum] 6| # tuned 6 lines: 3 AI-written (50%), 3 human-written
kal ask
Question your history in plain English — TF-IDF over messages, intents and paths, offline and instant. --llm has a model answer with snapshot citations.
$ kal ask "why do we retry logins" history most relevant to: 'why do we retry logins' [relevance 0] snap e8c7405a0044 add retry helper when 2026-07-26 02:18:16 author claude-code [ai:claude-opus-5] intent the IdP rate-limits bursts of logins files 1 modified
kal stats
Outcome scoreboard per author and per AI model: verification rate, approvals, revert rate. A free eval harness for any model committing to your repo.
$ kal stats author/model kind snaps verified approved reverted verify% revert% dev human 2 1 0 0 50% 0% claude-opus-5 ai 1 0 0 0 0% 0%
kal verify
Run your tests and stamp the result onto the snapshot; AI work climbs the trust ladder from unverified to tested.
$ kal verify "pytest" verification PASSED — stamped on 33223d8c4ba1 trust tier of HEAD is now: human-authored
kal approve
Human sign-off — the top of the trust ladder.
$ kal approve HEAD -m "ship it" approved 8cc7226d95ba; trust tier is now: human-authored
kal note
Attach revisable metadata (reviews, benchmarks) to an immutable snapshot without rewriting history.
$ kal note HEAD --add '{"reviewer":"jo"}' --kind review noted [review] on 8cc7226d95ba [review] 2026-07-26 02:18:18 by dev [human] { "reviewer": "jo" }
kal archive
Retire a branch but keep why it failed. Dead ends become searchable lessons neither humans nor agents repeat.
$ kal archive ssr-experiment -r "SSR doubled p95 latency" archived feature at 72d109c8e852 reason preserved: server-side rendering doubled p95 latency abandoned approaches (negative knowledge): feature (72d109c8e852, 2026-07-26 02:18:18) reason: server-side rendering doubled p95 latency
kal grep
Regex search the worktree or any snapshot.
$ kal grep retry app.py:4:def retry(n=3):
kal cat
Print a file exactly as it was in any snapshot.
$ kal cat v1.0 app.py kal: 'no object matches: v1.0'
Work with others
6Sync where intent, provenance and lessons travel with the code.
kal clone
Copy a repository from a path or URL — history, notes, trust stamps and lessons included.
$ kal clone https://vcs.example/payments cloned into /work/payments-clone (history, notes, and negative knowledge included)
kal push
Publish snapshots. Fast-forward safe; provenance travels with them.
$ kal push origin pushed main -> origin (3 objects, tip f28e2022e3f6)
kal pull
Fetch and integrate. Diverged? The remote tip is staged as main@remote for a normal merge — never a surprise rebase.
$ kal pull origin main: already up to date (0 objects fetched)
kal remote
Name your remotes; origin is configured automatically on clone.
$ kal remote add origin https://vcs.example/payments remote origin -> /work/payments origin /work/payments
kal serve
Turn any repo into a team server over HTTP. Every transferred object is hash-verified on arrival.
$ kal serve --writable kal serving /work/payments on http://127.0.0.1:8737 (writable) — Ctrl-C to stop
kal git
The bridge: mirror kal ⇄ git, with metadata in commit trailers that survive GitHub, PRs and rebases.
$ kal git sync && git log -1 exported 7 kal snapshot(s) to git (tip e949595ae6) — metadata in Kal-* trailers clone work Kal-Snap-Id: f28e2022e3f610cceb9e86df6605bceeedf6554ba7acfbecfc1be02debf4ce67 Kal-Author-Kind: human Kal-Intent: contribution from the clone
For AI agents & platforms
5Agents are first-class users, not an afterthought.
kal mcp
Serve the repository as MCP tools — Claude Code, Cursor, Codex and AZMX Code connect natively. --http for cloud IDEs.
$ kal mcp # any MCP client → tools/list {"jsonrpc":"2.0","id":2,"result":{"tools":[ {"name":"kal_status"}, {"name":"kal_snap"}, {"name":"kal_why"}, {"name":"kal_ask"}, {"name":"kal_undo"}, {"name":"kal_verify"}, {"name":"kal_blame"}, {"name":"kal_stats"}, …]}}
kal watch
Micro-checkpoint daemon: any agent editing files leaves a timeline you can rewind.
$ kal watch kal watch: checkpointing /work/payments every 5.0s once changes settle [14:02:11] checkpoint 8c2f91ab02d1 (3 files) [14:05:37] checkpoint f671bb0c9a44 (1 files)
kal context
A token-budgeted briefing of the repo for any model. --agents-md writes your AGENTS.md.
$ kal context # Repository context: payments Branch: main | Generated by kal v0.7.0 ## Abandoned approaches (negative knowledge — do not repeat) - feature (72d109c8e852): server-side rendering doubled p95 latency ## Files - README.md (24 bytes) - app.py (71 bytes) ## Recent history (message · intent · author · trust) - 8cc7226d95ba merge feature intent: - author: dev[human] · trust: human-authored · files changed: 1 - e2bd12335d35 friendlier greeting intent: - author: dev[human] · trust: human-authored · files changed: 1 - 72d109c8e852 feature docs intent: document the feature author: dev[human] · trust: human-authored · files changed: 1 …
kal export
Consent-gated, secret-scrubbed training data: intent → diff → outcome, verified work as positives.
$ kal export --training {"author_kind": "human", "diff": "--- a/README.md\n+++ b/README.md\n@@ -0,0 +1 @@\n+# payments\n\n--- a/app.py\n+++ b/app.py\n@@ -0,0 +1,2 @@\n+def hello():\n+ return 'hi'\n", "id": "70b33dfef2896315457243e1be6bbd8c616564d706d643445145e9eebcf886fd", "intent": "starting the payments service", "label": "unlabeled", "message": "scaffold service", "model": null, "outcome": {"approved": false, "reverted": false, "verified_fail": false, "verified_pass": false}, "type": "change"} {"author_kind": "ai", "diff": "--- a/app.py\n+++ b/app.py\n@@ -1,2 +1,5 @@\n def hello():\n return 'hi'\n+\n+def retry(n=3):\n+ return n\n", "id": "e8c7405a0044569741196a4022f4516173efbbaaa2cb3fea8882ceb3cc9f6763", "intent": "the IdP rate-limits bursts of logins", "label": "unlabeled", "message": "add retry helper", "model": "claude-opus-5", "outcome": {"approved": false, "reverted": false, "verified_fail": false, "verified_pass": false}, "type": "change"} {"author_kind": "human", "diff": "--- a/app.py\n+++ b/app.py\n@@ -3,3 +3,4 @@\n \n def retry(n=3):\n return n\n+# tuned\n", "id": "33223d8c4ba1760bcb28a827362fb8e1b2717427ef424d97b888ba1f52dfd708", "intent": "automatic work-in-progress checkpoint", "label": "positive", "message": "checkpoint", "model": null, "outcome": {"approved": false, "reverted": false, "verified_fail": false, "verified_pass": true}, "type": "change"} …
kal config
Everything tunable — llm.provider (Anthropic or AZMX), celebrations, export consent, remotes.
$ kal config author { "name": "dev", "kind": "human" }