Turn it on
- Session hooks for Claude Code (the repository’s
.claude/settings.json), Cursor (the repository’s.cursor/hooks.json), and Codex (~/.codex/config.toml, in your home folder).--agents claude,cursorlimits which ones, and--codex-config <path>points to another Codex config. - Two git hooks.
prepare-commit-msgadds aKodus-Trace:trailer to each commit message, linking the commit to its session.pre-pushstarts the distillation in the background. - A fetch setting so a plain
git fetchalso brings down the shared decisions.
kodus trace status: sessions and turns captured, decisions (local and shared), hooks installed, and any problem it ran into. Remove the hooks with kodus trace disable (add --dry-run to preview). Disabling removes only the hooks: captured sessions stay on your machine, and events already sent to Kodus stay there.
What is captured
Each turn of an agent session: the prompt and response, a one-line summary of each tool the agent used, the files it read and changed, its commands, and token usage. Records live under~/.kodus/sessions, outside the repository, and are deleted after 90 days.
Before saving or sending events, the CLI masks secret patterns it recognizes. Captured content can still contain sensitive data. Keep credentials out of sessions you capture. To stop capturing new sessions, run kodus trace disable.
Capture works with no account.
When you are signed in with a login or a team key, the CLI also sends each session’s events after masking recognized secrets to Kodus: the prompts and responses, the tools the agent called with their inputs and outputs, the files read and changed, the commands, token usage, the branch, the git remote URL, and commit ids. Kodus stores them for your organization. When a session ends, a model reads them to extract decisions, on your organization’s BYOK model when it has one and on a Kodus-managed model otherwise. These events count toward the team’s 1,000 requests per hour.
How decisions are made
Ongit push, a background job summarizes each commit on your branch that is not on the default branch. It then asks a coding agent CLI on your machine to turn those summaries and the branch’s captured sessions into decisions. It uses the first of claude, codex, gemini, and cursor-agent that it finds. That tool receives the commit messages, the file names, and the redacted prompts and responses of the sessions, so they go to its provider as in any other use of it. With none of them installed, capture still works and no decisions are written.
The job never delays or fails a push. It writes the decisions to a branch named kodus/trace/v1 and pushes that branch to the same remote, so a teammate’s clone gets them with git fetch. Each push replaces the record of that branch.
Read the decisions
Pass the paths you are about to change. No subcommand is needed.--remote <name> picks the remote whose decision branch to read.
Each decision shows:
- Type:
architectural_decision,convention,tradeoff,implementation_detail,tooling, orother. - Origin:
humanif you asked for it,agentif the agent chose it unprompted,collaborativeif you settled it together. - Confidence, from 0 to 1, as judged when the decision was written.
- Scope, the paths it applies to, and the source:
local(recorded here) orbranch(shared by someone else). - An id, the handle for
forgetandpin.
status, separate it with --: kodus trace -- status.
Correct the record
Browse sessions
Environment variables
Related
AI Agents
Skills and loops for coding agents.
Command Reference
All
kodus trace commands.