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 92f15ff0e493 scaffold service when 2026-07-26 23:29:50 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 e20d721baa15 add retry helper when 2026-07-26 23:29:50 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 92f15ff0 dev [hum] 1| def hello(): 92f15ff0 dev [hum] 2| return 'hi' e20d721b claude-code [ai] 3| e20d721b claude-code [ai] 4| def retry(n=3): e20d721b claude-code [ai] 5| return n 6337fc91 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 705455e3468b) 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 6337fc916cdc 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 e20d721baa15 add retry helper when 2026-07-26 23:29:50 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 a144cf55ea) — metadata in Kal-* trailers clone work Kal-Snap-Id: 04137123f47c0cbf61786d4781b4cf95613a8c409687c203824f26213e805f27 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.