RepoTruth

RepoTruth records what an AI coding agent actually did, then reviews that evidence against simple repository rules before you accept the work.

It is for the moment when an agent says "I read the docs" or "tests passed" and you want to see the recorded commands, file reads, file changes, test runs, and final-answer claims.

Trust recorded evidence, not the final answer.

Quick Start

RepoTruth needs Node.js 18 or newer.

Use RepoTruth when you want to accept agent work based on recorded local evidence, not just the agent's final answer. The first run records the session, opens a local report, and shows any UNKNOWN gaps that need better evidence before you trust specific claims.

From the repository you want to monitor, run:

npm exec --package repo-truth@latest -- repo-truth

In an interactive shell, no-arg repo-truth sets up RepoTruth if needed, then starts the preferred available agent with a live browser report. In CI or non-interactive use it prints help instead of starting an agent.

Recommended path:

1. Start a monitored agent session with repo-truth or repot start.
2. Let the agent work normally while RepoTruth records local evidence.
3. Watch Policy alignment, Drift details, and Improve future alignment in the local report before accepting the work.
4. Use Verify current work for optional checks on the current workspace. These checks help review the work now; they do not prove the agent ran them before finishing.

You can also install it once:

npm install -g repo-truth

Initialize the repository you want to monitor:

repot setup

The starter truth.yml keeps required finish commands empty, then enables conservative claim checks for read and tested. If the final answer says files were read or tests passed, RepoTruth asks for matching recorded evidence; missing evidence stays UNKNOWN instead of being treated as PASS.

Start Codex with RepoTruth live review:

repot start

RepoTruth prints a local review URL and keeps it live while the agent runs:

RepoTruth live review: http://127.0.0.1:54321/
RepoTruth recording: codex (http://127.0.0.1:54321/)

The live browser report is loopback-only. Do not expose .truth/runs or the report URL on a network; traces can include command strings, review evidence, and paths from the local workspace.

The agent process receives REPOTRUTH_RECORDING=1, REPOTRUTH_REVIEW_URL, REPOTRUTH_RECORDING_NOTICE, and live collector variables:

• REPOTRUTH_COLLECTOR_URL
• REPOTRUTH_COLLECTOR_TOKEN
• REPOTRUTH_COLLECTOR_ID
• REPOTRUTH_COLLECTOR_TYPE
• REPOTRUTH_COLLECTOR_VERSION

Hooks can report trusted live evidence with commands such as repot collect file.read --path README.md, repot collect file.write --path src/app.js, or repot collect agent.final --message "Done". RepoTruth signs those events from the local collector; repot event remains manual evidence. This is a transparent recording notice; RepoTruth does not rewrite your prompt or force the agent to say anything.

repot start is a recording wrapper for trusted local agent work, not a sandbox for untrusted commands. The wrapped process receives the collector token so supported hooks can report evidence; an untrusted child process could submit false local evidence.

Trust boundary summary:

• RepoTruth is a review tool, not a sandbox.
• A wrapped agent receives the collector token so supported hooks can report evidence; untrusted child processes can submit false local evidence.
• Strong evidence means RepoTruth can verify how an event was captured, not that the whole machine state is tamper-proof.

For supported agent starts, RepoTruth sets up temporary local agent hooks by default so the live report can capture signed tool, file, command, and final-answer evidence before the agent exits:

repot start
repot start claude
REPOTRUTH_EXPERIMENTAL_CURSOR_HOOKS=1 repot start cursor

Auto hooks require the live wrapper collector. For an arbitrary or custom agent command, use the generic live wrapper form:

repot start --auto-hooks -- codex
REPOTRUTH_AUTO_HOOKS=1 repot start -- codex

Replace codex with another supported agent command or wrapper when needed. To opt out for one run, pass --no-auto-hooks:

repot start --no-auto-hooks
repot start --no-auto-hooks -- codex

Auto hooks install temporary RepoTruth-managed hook entries for supported agents. Those entries call repot hook-bridge, which forwards normalized hook payloads to the signed live collector. RepoTruth removes only its own current lease when the wrapper exits normally and leaves user hooks alone. If a crashed run leaves stale RepoTruth-managed entries behind, leftover entries no-op when the collector environment is absent; older stale RepoTruth-managed entries are pruned during later auto-hook setup.

Codex and Claude have supported temporary hook adapters. Cursor is still an experimental adapter and requires REPOTRUTH_EXPERIMENTAL_CURSOR_HOOKS=1. Copilot does not have a temporary hook adapter yet; use normal session import or another supported evidence path. For Codex, the live wrapper adds the one-off hook trust bypass argument when auto hooks are active, so you do not need to pass it yourself.

Check the setup any time:

repot status

repot status shows setup readiness, verification candidates, and an agent coverage matrix for Codex, Claude, Cursor, Copilot, and custom wrappers. The matrix separates CLI availability, live-start support, temporary hook support, transcript import support, evidence strength, and the recommended next command for each agent.

Documentation

| Start here | Use this when you need | | --- | --- | | Documentation hub | A guided map of all RepoTruth docs. | | Getting started | Install, set up, run the first review, try the sample report, and uninstall. | | Workflows | Day-to-day commands for live review, custom agents, named traces, recording, and CI-friendly use. | | Policy | Author truth.yml, generated checks, profiles, claim checks, protected paths, and forbidden commands. | | Reports and evidence | Interpret PASS, DRIFT, WARN, UNKNOWN, actionable evidence gaps, evidence strength, receipts, and trust limits. | | Session sources | Review RepoTruth, Codex, Claude, Cursor, and Copilot sessions. | | Learning and MCP | Generate learned instruction proposals and use RepoTruth over MCP. | | Troubleshooting | Fix missing CLIs, stale traces, UNKNOWN results, path issues, and npm/npx confusion. | | Architecture | Understand the evidence lifecycle and major modules. | | Development | Run tests, packaging checks, extension checks, and release sanity checks. |

RepoTruth also ships a VS Code extension. See extensions/vscode/README.md for setup, commands, and extension configuration.

Common Workflows

| Goal | Command | | --- | --- | | Set up if needed and start the preferred agent | repo-truth or npm exec --package repo-truth@latest -- repo-truth | | Set up RepoTruth in the current repo | repot setup | | Start Codex with live review | repot start or repot codex | | Start Claude with live review | repot start claude or repot claude | | Start Cursor Agent with live review | repot start cursor or repot cursor | | Start Copilot CLI with live review | repot start copilot or repot copilot | | Run any custom command with live review | repot start -- <command> | | Use a custom evidence label | repot start --agent review-bot -- <command> | | Serve the latest browser report | repot review --serve | | Watch the latest report in a terminal | repot review --watch | | Print the human review report | repot audit | | Record one command as evidence | repot record --agent codex -- npm test | | List local sessions | repot list | | Import and review a local session | repot open <session-id> | | Generate learned instruction proposals | repot learn | | Serve RepoTruth MCP resources and tools | repot mcp | | Preview full cleanup | repot uninstall |

After a global install, use the global binaries directly:

npm install -g repo-truth
repo-truth
repot start

npx repo-truth does not mean "use my global install"; npm may run a local dependency, npm cache entry, or freshly fetched package instead. Use npm exec when you want npm to fetch an explicit package version:

npm exec --package repo-truth@latest -- repo-truth
npm exec --package repo-truth@latest -- repot setup
npm exec --package repo-truth@latest -- repot start
npm exec --package repo-truth@latest -- repot review --serve

When RepoTruth runs in an interactive terminal, it checks the npm registry in the background at most once per day. If the cached result shows a newer release, it prints a short stderr notice with the global update command and the npm exec --package repo-truth@latest form. Set REPOTRUTH_UPDATE_CHECK=0 to hide this notice.

repot start and repot codex overwrite .truth/runs/latest.jsonl so repeat runs do not stop on a stale trace. Pass --trace .truth/runs/<name>.jsonl when you want to keep a named trace.

Trace files should be treated as sensitive local review artifacts. Avoid putting secrets in command arguments because command strings are recorded as evidence.

If a known agent command is missing, RepoTruth stops before starting live review and prints install, verify, and fallback guidance. It does not install or fetch anything automatically.

Codex and Claude have first-class live hook support. Cursor live hooks are experimental and require REPOTRUTH_EXPERIMENTAL_CURSOR_HOOKS=1; Cursor stream-json imports can provide structured adapter evidence. Copilot review currently relies on wrapper/session evidence or local session import rather than temporary auto hooks. Custom wrappers can still produce strong evidence when they call the live collector with repot collect.

Use repot setup, repot status, repot start, repot record, repot review, repot list, repot import, and repot open. The older internal command forms were removed in the breaking npm upgrade.

Try The Sample Report

From this source checkout:

node bin/truth.js review --policy examples/truth.yml --trace examples/trace.fail.json --serve

Open the printed local URL to see a sample report with findings.

Limits And Trust

RepoTruth is experimental 0.x tooling. It helps reviewers see recorded evidence, but it does not replace code review.

RepoTruth is not a sandbox, a security boundary, or a guarantee that the agent behaved correctly. It can only report what it captured or inferred from available records.

Strong evidence means RepoTruth can verify how an event was captured. It does not mean the whole machine state is tamper-proof.

If RepoTruth cannot confirm something from recorded evidence, it says UNKNOWN instead of guessing.