Skip to main content
A diff shows what changed. Kodus Trace keeps why. It captures the coding agent sessions in a repository, turns the branch you push into decisions (architectural choices, conventions, tradeoffs), and lets you or an agent read the decisions recorded for a path before changing it. Local capture and lookup run through the CLI. Using redacted Trace decisions as context in PR reviews is a private alpha on Kodus Cloud for the same repository.

Turn it on

Run it inside the repository. It installs:
  • 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,cursor limits which ones, and --codex-config <path> points to another Codex config.
  • Two git hooks. prepare-commit-msg adds a Kodus-Trace: trailer to each commit message, linking the commit to its session. pre-push starts the distillation in the background.
  • A fetch setting so a plain git fetch also brings down the shared decisions.
The pre-push hook shares its file with the review hook from kodus hook install. With both installed, a push does not start the distillation, so no new decisions are written. kodus hook uninstall removes only the review hook and leaves Trace’s.
Check what it did with 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

On git 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.
A directory returns everything recorded under it. A file returns everything whose scope covers it, including decisions recorded for its directory. Reading uses what is already on your machine and makes no network call. --remote <name> picks the remote whose decision branch to read. Each decision shows:
  • Type: architectural_decision, convention, tradeoff, implementation_detail, tooling, or other.
  • Origin: human if you asked for it, agent if the agent chose it unprompted, collaborative if 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) or branch (shared by someone else).
  • An id, the handle for forget and pin.
An empty result is a normal answer, with exit code 0. It means nothing is recorded for those paths yet, or capture is off. If a path has the name of a subcommand, such as status, separate it with --: kodus trace -- status.

Correct the record

Both are saved locally. When the decision is on the shared branch, they are also published to it, so the team sees the correction.

Browse sessions

Serves your local sessions in the browser. It reads the local store only.

Environment variables

AI Agents

Skills and loops for coding agents.

Command Reference

All kodus trace commands.