Boundary · Local-first · Agent-time
Every agent change gets a first pass.
Review tools ask whether code looks wrong. CodeTruss proves whether the agent stayed inside its task contract and whether the exact final Git state passed your checks. Its local Boundary records the starting point, classifies every change, runs 15 shared analyzers and your verification commands, then leaves an integrity-signed receipt on your machine.
- Boundary
- Local first-pass gate
- History
- Explicit receipt sync
- Health
- Hosted codebase audit
Reproduced failure case
v0.1.1 signed PASS. v0.2.14 correctly fails.
See the exact adversarial fixture, artifact hashes, immutable-snapshot fix, and the limits of what a signed receipt can prove.
§ 01 — Quickstart
One guided setup. Automatic after that.
codetruss setupSetup proposes conventional source roots without silently allowing the whole repository, shows every detected verification command and its exact fingerprint before trust, installs the selected automatic checks, and runs diagnostics. It uploads nothing. Codex requires one final action: open /hooks and approve the exact project hook. Then use Claude Code, Codex, or your normal commit flow without a per-change CodeTruss command.
codetruss review --task "Review my current agent changes"The manual review path needs no account, policy, or sync. Without an allow policy, changed files are deliberately unexpected, so REVIEW_REQUIRED exits with code 1 while still producing valid signed evidence.
codetruss verify latestcodetruss run \
--task "Add password-reset rate limiting" \
-- codex exec "Implement password-reset rate limiting"Add task-specific --allow, --deny, or --verify only when this run intentionally differs from the committed repository policy.
Integrity receipt · latest
REVIEW_REQUIRED
- Task
- Add password-reset rate limiting
- Scope
- 2 allowed · 1 unexpected
- Analysis
- 15 local analyzers · hosted scores N/A
- Reason
- CI workflow changed outside approved scope
- Verification
- npm test · exit 0
The verdict is calculated from recorded facts. A model does not decide whether the run passed. The signature detects changes after signing; it does not prove the run happened in trusted infrastructure or that every recorded fact was truthful.
§ 02 — Method
Five steps between the prompt and the pull request.
- 01
Record the boundary
CodeTruss records the starting commit, current working-tree state, task, allow globs, and deny globs before the agent runs.
- 02
Run any agent
The command after -- can be Codex, Claude Code, another agent CLI, or an ordinary shell command. CodeTruss does not stage, commit, or clean its work.
- 03
Inspect the real diff
Added, changed, deleted, renamed, staged, unstaged, and untracked files are classified as allowed, denied, unexpected, or in scope by inference from this turn — which the receipt says plainly.
- 04
Analyze and verify
All 15 shared registry analyzers run locally on the change, a local security pass runs the differentially-validated rule subset, sensitive surfaces are called out, and your own lint, test, or build commands execute.
- 05
Integrity-sign the receipt
A Markdown and JSON receipt records the evidence, hashes, explicit reasons, and deterministic verdict. Its signature detects post-signing changes; it does not prove trusted execution or truthful analysis.
Scope policy
Deny wins. Unmatched is visible.
Allow and deny globs make the requested boundary concrete. Renames are checked at both the old and new path, so moving a protected file cannot hide it.
Sensitive surfaces
Risk is flagged even when allowed.
CI, infrastructure, migrations, secrets, deploy configuration, dependency manifests, and lockfiles always receive an explicit callout.
One registry
15 shared analyzers, on your machine.
The CLI consumes the same 15-analyzer database-free registry as the web app and filters findings to the change. A local security pass runs alongside it — the same engine, rules, and taint solver as the hosted audit, restricted to the rule subset differentially validated against the hosted parser. It is a separate pass, not a sixteenth analyzer, so the receipt can state the registry count truthfully and name this pass and its limits beside it. It is bounded — 5 seconds per file, 5 minutes per pass — and any file a ceiling cut is named, because a rule that did not run reported nothing, which is not the same as finding nothing. Python is analyzed locally too, behind a grammar pack you install deliberately; because that pack is the hosted parser, Python is scanned with the whole rule pack rather than the narrower JavaScript subset. Hosted full-codebase audits add the cross-file symbol graph, the full rule pack for the JavaScript family, and the route authorization graph that decides missing authorization and cross-tenant object references. Local receipts mark hosted Health scores N/A instead of scoring incomplete evidence.
§ 03 — Verdicts
A decision with reasons, not another wall of review prose.
PASS
The change stayed in scope and every configured gate passed.
Expected paths only · no blocking diff finding · verification green
REVIEW_REQUIRED
The work may be valid, but a person needs to accept the scope or risk.
Unexpected or denied path · sensitive surface · medium+ finding · LLM advisory
FAILED
The agent, a required check, or a high-risk security gate failed.
Agent exit · failed verify command · high/critical security or dependency finding
Exit codes are automation-ready: PASS = 0, REVIEW_REQUIRED = 1, FAILED = 2.
§ 04 — Privacy
Local means local. The network boundary stays explicit.
| Action | Leaves your machine? | Destination |
|---|---|---|
| Installers and direct package install | YES · INSTALL ONLY | CodeTruss release metadata and package artifact |
codetruss grammars install | YES · EXPLICIT | CodeTruss downloads host · fetches the ~722 KB Python grammar pack (tree-sitter runtime JS and WASM, plus the grammar WASM) — executable code, downloaded only when you run this command, checked against SHA-256 digests compiled into the binary, and never fetched during a scan. grammars list, status, and uninstall make no request. |
| Deterministic commands: run, review, report, list, metrics, setup, init, verify, verify-receipt, verify-policy, hooks, grammars list/status/uninstall, help, version | NO CODETRUSS CONTACT | Local process only |
| Your verify commands | Only if that command uses the network | Whatever your command contacts |
--llm slop review | YES · OPT-IN | Your selected provider, using your key or local login |
codetruss auth login | YES · EXPLICIT | CodeTruss device/session endpoints · no source, patch, or receipt upload |
codetruss auth status/logout | YES · EXPLICIT | Verify or revoke the saved credential at CodeTruss · no source, patch, or receipt |
codetruss sync | YES · EXPLICIT | The only command that uploads a receipt · redacted receipt, never the patch |
That is every command the CLI has, not a selection. If a command is missing from the table above, treat it as a documentation bug and tell us.
Sync keeps the task, relative file paths, commit hashes, scope, analysis profile, analyzer findings, verdict, reasons, invocation kind and provenance, optional Claude/Codex hook surface, issuing CLI version, and any LLM summary. It removes the absolute repository path, agent command arguments/start errors, and verification commands/output; the patch is never uploaded. The CLI has no background usage telemetry, receipt upload, or synchronization..codetruss.yml is the reviewable policy that may be committed. Private evidence under.codetruss/ is added to the repository-local Git exclude; CodeTruss verifies it remains ignored and refuses to continue if evidence becomes tracked or is routed through unsafe paths. Website analytics may record a non-PII install-command copy or design-partner-link click as a distribution or interest proxy; neither proves installation, activation, consent, or enrollment.
Optional BYO-key slop review
Add --llm for a focused review of unnecessary abstractions, duplicated logic, placeholders, verbose comments, and work that does not serve the task. Choose Anthropic, OpenAI, or authenticated Claude Code with credentials you control—never a CodeTruss key. CodeTruss supplies a bounded task, reviewed diff prefix, and fixed schema; the receipt discloses coverage, and a truncated review cannot pass.
OPENAI_API_KEY=... codetruss review --llm \
--provider openai \
--task "Review the staged implementation" \
--staged§ 05 — Automation
Put the guardrail where agents already work.
Install a staged pre-commit review, an exact-turn Claude Code hook, an exact-turn Codex hook, or all three. Agent hooks capture the prompt-time baseline, return fast scope feedback after native edits, then run the analyzers and trusted verification commands once at the stop boundary. The wrapper additionally records the launched agent command and its exit status.
- 01Pre-commit checks exactly what is staged.
- 02Per-edit callbacks stay fast: path scope, sensitive surface, dependency.
- 03One final receipt covers every tool path and returns repair feedback.
- 04Codex requires a one-time, hash-specific trust review in
/hooks; rerun it after the runner changes.
codetruss setup§ 06 — Agent Skill
Teach the agent to enforce the boundary, not route around it.
The official CodeTruss integration wrappers are MIT-licensed and published in the open integration repository. One canonical Agent Skill teaches Claude Code and Codex to propose a narrow policy, invoke the local acceptance gate, diagnose hooks, and explain receipt evidence without weakening a failed check.
Separate CLI · same privacy boundary
Install the CodeTruss CLI first. The plugin contains instructions and manifests; it wraps the separately installed local binary. It adds no MCP server, background service, hosted analyzer, or automatic upload path. Deterministic checks remain on-machine, while provider-backed --llm review and codetruss sync remain separate, explicit opt-ins.
Distribution status · owned marketplace live · Agent Skills listing live with all three listed security scans passing · clean-profile Claude Code and Codex installs verified · OpenAI and Anthropic directory submissions prepared, not approved or listed
claude plugin marketplace add CodeTruss/codetruss-plugins
claude plugin install codetruss@codetrussInstalls from the live CodeTruss-owned marketplace; this does not imply Anthropic marketplace approval.
codex plugin marketplace add CodeTruss/codetruss-plugins
codex plugin add codetruss@codetrussInstalls from the live CodeTruss-owned marketplace; this does not imply OpenAI Plugin Directory approval.
npx --yes skills add CodeTruss/codetruss-plugins --skill codetruss --agent claude-code codex -yThe live listing shows all three directory security scans passing. Listing status does not imply independent installs or adoption.
§ 07 — Reference
The core local commands.
setupGuide scoped policy, exact verification-command trust, hook installation, and diagnostics locally.
runWrap an agent command and review the changes it produces.
reviewReview an existing working-tree or staged diff.
reportPrint a receipt as Markdown or structured JSON.
listList local receipts, newest first.
metricsAggregate verified local receipts into privacy-safe activity, verdict, invocation, D7 receipt-pattern, and hook-health counts without a network request.
init --allow <glob>Manually create a documented .codetruss.yml policy; repeat allow and deny flags as needed.
verifyValidate post-signing integrity and the receipt’s referenced evidence.
verify-receipt <file>Check a receipt produced elsewhere, outside any repository: integrity from the receipt itself, provenance only against a --public-key obtained from the signer.
verify-policy trustAfter inspection, trust the exact repository verification-command fingerprint for automatic execution.
auth loginAuthorize explicit receipt sync with a scoped, revocable organization credential.
grammarsList, install, check, or remove an optional language grammar pack. install is the only subcommand that downloads anything; the artifacts are pinned to SHA-256 digests compiled into this binary.
hooks installInstall pre-commit, Claude Code, and/or Codex hooks.
hooks statusShow which supported repository hooks are installed.
hooks doctorValidate hook wiring, runner integrity, policy, and CLI resolution.
syncExplicitly upload one redacted receipt to a CodeTruss organization; never the patch.
§ 08 — Commitment
The CLI is free forever.
Installing CodeTruss Boundary, running every command listed above, and producing signed receipts cost nothing, and they always will. There is no seat count, no trial clock, and no feature that quietly stops working once you depend on it.
The paid line sits at the network boundary, in exactly the place the table in § 04 already draws it: local stays free, hosted is billed. And we do not claw back — anyone already syncing receipts before we priced it keeps that free permanently.
