kal in five minutes
Eight steps, every one showing the real output you will see. The same tour lives in
your terminal as kal help tour.
Make a repository
kal adds a hidden .kal/ directory and leaves your files alone. If a .git
already exists here, the two coexist quite happily.
$ kal init initialized empty kal repository in /work/payments/.kal
Snapshot — with an intent
-m is what changed. -i is why, and it is the habit that changes everything.
$ 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
why, ask and every AI tool
you point at the repo can read later.Let an agent contribute — with attribution
When an AI makes the change, it says so. Platforms set three environment variables and every snapshot is attributed automatically; by hand it is two flags.
$ kal snap -m "add retry helper" -i "the IdP rate-limits bursts" --agent claude-code 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
{name, kind: human|ai, model, session} inside the immutable snapshot — everything that
follows is built on it.Ask who wrote each line
A question git cannot answer: human or model? Line by line, with 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
Break something, then un-break it
Every operation is journalled with its before-and-after state. Undo reverses the last one — snap, merge, reset, anything — and because snapshots are never destroyed, undo is undoable too.
$ 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
Prove the work
Run your tests through kal and the result is stamped onto the snapshot. AI-authored work climbs a trust ladder — unverified, tested, approved — and those stamps become per-model scorecards.
$ kal verify "pytest" verification PASSED — stamped on 33223d8c4ba1 trust tier of HEAD is now: human-authored
$ 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%
Question your history
Plain-English search across messages, intents and paths — offline and instant. Add
--llm and a model answers from the repository's own briefing, citing snapshots.
$ 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
Stay friends with git
One command mirrors everything into an ordinary .git, with intent and attribution in
commit trailers that survive GitHub, pull requests 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
That's the tour
Next: the command reference with real outputs,
how kal thinks, or the git translation table.
Run kal awards too — you have already earned your first achievement.