Trace 发布本地优先的 AI 编码智能体执行追踪工具

Git stores commits. Trace stores execution.

AI coding agents now write, run, and ship code on real machines. Trace gives every session a complete local record of what changed, what ran, what it cost, and what looked risky, plus a one-click way to roll it back.

It is local-first: the daemon and dashboard bind only to 127.0.0.1, there is no account, and your project data stays on your machine by default.

• Landing: https://trace-landing-blue.vercel.app
• Docs: https://taxcollector23.github.io/trace/
• Repo: https://github.com/TaxCollector23/trace

Why it exists

Companies now give every engineer an autonomous coding agent, and those agents have a shell. They install packages, rewrite configs, run migrations, delete files, and push branches on real machines with real credentials, often faster than a person can read what scrolled past.

Most of the time that is fine. The failure cases are the problem: a session wipes the wrong directory while cleaning up, force-pushes over a branch, deletes a failing test instead of fixing the bug, commits an API key, or runs a piped shell installer. By the time anyone looks, the change has landed and the context is gone.

Trace makes every session something you can see, stop, and undo:

• A git checkpoint before anything changes, so rollback is one click and the safety net is already in place.
• Every file change as a diff you can read: the authoritative patch, reviewed like a pull request.
• A guard on every command, classified in real time as allow, warn, require-approval, or block. Destructive commands (rm -rf, force-push, piped shell installers, raw disk writes) are stopped before they run.
• Secret scanning that catches and redacts keys and tokens in a diff.
• Cost per session, token spend by model, so a runaway loop is visible immediately.
• PR ratification: the same checks over a pull request, in the dashboard or in CI, with a clear pass / review / block verdict.

Every check is deterministic pattern matching, with no LLM in the guard path and no API key, so verdicts are instant, free, and identical on every machine. The detection is measured against a labeled red-team corpus you can reproduce yourself, and everything runs on 127.0.0.1. Your code never leaves your machine.

Install

npm install -g trace-agent-cli

This installs the trc command on macOS, Linux, and Windows.

Quickstart

trc init
trc run "<your agent>"
trc dashboard

The dashboard opens locally at http://127.0.0.1:<port> (binds to 127.0.0.1 only). Roll back a run's changes with trc rollback.

CLI commands

Local dashboard

Served by the Rust daemon at http://127.0.0.1:<port> (prefers 8757, falls back to the next free port). Sections: Dashboard (with a live status strip for the policy + red-team benchmarks and Ratify), Session Timeline, Patch Review (with a Git diff view), Token Spend, Command Risk (command decisions, policy findings, secret warnings), Trace Analytics, Benchmarks, Rollback Points, Integration Status, and Ratify (deterministic PR review against a connected GitHub repo). It has clean empty/loading/error states, status badges, and a clear local-only notice. No fake data in production.

Features

• Complete execution trace: prompts, commands, file changes, and cost tied to one run
• Agent run timeline and Git checkpointing
• Patch review grounded in the real Git diff
• File-change tracking with a debounced watcher
• Rule-based command guarding (allow / warn / require approval / block), understands evasions the naive blocklist misses: pipe-to-shell (curl ... | sudo bash), download-then-exec, base64-decoded payloads, find ... -delete, raw block-device writes, DB drops
• Deterministic policy engine: secret detection, missing tests on sensitive paths, swallowed errors, hardcoded localhost, dependency/lockfile changes, and more, with a real labeled-fixture benchmark (trc self-check / the dashboard's Benchmarks page) proving precision and recall rather than asserting it. No API key required, it's pure pattern matching.
• Red-team benchmark: an adversarial corpus (dangerous commands incl. evasions, planted API keys, unsafe prompts) run through the real engines and scored for recall and false positives, surfaced in trc self-check, the API, and the dashboard
• Ratify: run the policy engine over a GitHub pull request's files and get a pass / review / block verdict, from the dashboard, trc ratify <pr>, or the API. No key.
• trc check: scan any file or script through the guard + secret scanner without executing it; non-zero exit for CI gating
• CI review: trc review-diff runs the same deterministic engine from a bare git checkout, no daemon needed; the GitHub Action installs and runs it automatically
• Local secret detection with redaction (raw secrets are never stored)
• Cost/token tracking with honest partial-data handling
• Build/test result recording and deterministic failure diagnosis
• Rollback center backed by Git
• Local SQLite history
• GitHub repo reading: reads commits, PRs, and file contents directly from your repo (including private repos) via an authenticated, read-only token
• Cross-platform desktop shell (macOS, Windows, Linux)

Integrations

Each lives under integrations/ and connects to the local daemon.

• Claude Code: session, command, and edit hooks; Bash commands are enforced (integrations/claude)
• Cursor: session, command, and edit hooks plus MCP tools; shell commands are enforced (integrations/cursor)
• OpenCode: V1/V2 guard plugin plus MCP tools; Bash commands are enforced (integrations/opencode)
• Codex: lifecycle hooks for CLI, desktop, and IDE plus a wrapper fallback; Bash commands are enforced after the hook is trusted, while file edits are reviewed after the call (integrations/codex)
• Windsurf: MCP server, read-only (integrations/windsurf)
• Aider: run through trc run aider; no standalone installer is advertised yet
• VS Code: extension, not yet published to the marketplace (integrations/vscode)
• GitHub: App + Action running the deterministic policy engine (trc review-diff) and posting sanitized summaries (integrations/github)

Run trc integrations install all to wire up Claude Code, Codex, Cursor, Windsurf, and OpenCode in one step. It starts the local daemon and prints the dashboard link. Restart the running agents; Codex also needs /hooks approval before its command guard becomes active.

GUI tools are observed via file changes and Git diffs; full command guarding requires supported hooks or running through trc run.

Architecture

• CLI (trc) handles user commands, runs the wrapped command, and hosts the daemon in a detached child process.
• Daemon (Axum) owns the local API, SQLite persistence, and dashboard serving, bound to 127.0.0.1 only.
• Core holds shared models, guard rules, the deterministic policy engine, the secret scanner, the Ratify verdict logic, the benchmark corpora, cost estimation, git/GitHub inspection, and the database schema. All deterministic.
• Web is visualization only.

See ARCHITECTURE.md for the full, module-by-module reference.

• SQLite (~/.trace/trace.db) stores local history.
• Git provides checkpoints and rollback.

Repository structure

trace
├── README.md
├── docs/                  # Markdown docs (single source)
├── crates/
│   ├── trace-cli/         # Rust CLI (binary: trc; hosts the daemon)
│   ├── trace-daemon/      # Rust local API + localhost GUI server
│   └── trace-core/        # shared logic
├── apps/
│   ├── web/               # React + Vite local dashboard
│   ├── desktop/           # native desktop shell (Tauri) wrapping the dashboard
│   ├── landing/           # public landing site (Vercel)
│   └── docs/              # docs site → GitHub Pages (renders /docs)
├── integrations/
│   ├── github/            # GitHub App / Actions
│   ├── vscode/            # VS Code extension
│   ├── cursor/            # Cursor MCP server + hook
│   ├── windsurf/          # Windsurf MCP server
│   ├── opencode/          # OpenCode plugin
│   ├── shared/            # Claude/Cursor lifecycle hook
│   ├── claude/            # Claude Code hooks adapter
│   ├── codex/             # Codex CLI adapter
├── packages/
│   └── npm/               # npm wrapper package
├── homebrew-trace/        # Homebrew formula (mirrors the tap repo)
├── firebase/              # optional static mirror / reserved identity
├── scripts/               # install.sh, install.ps1
└── .github/workflows/     # release.yml, landing-deploy.yml, ci.yml

Development setup

# Rust
cargo build
cargo test

# Dashboard (embedded by the daemon in release builds)
cd apps/web && npm ci && npm run dev   # or: npm run build

# Landing site
cd apps/landing && npm ci && npm run dev

# Run the daemon / CLI directly
cargo run -p trace-daemon
cargo run -p trace-cli -- --help

Deploying the public surfaces

The public surfaces are marketing/onboarding only and never touch the local daemon.

• Vercel (landing): deployed from apps/landing (Root Directory apps/landing, build command npm run build, output dist) to the landing project at https://trace-landing-blue.vercel.app. Set VITE_MINTLIFY_DOCS_URL to the deployed docs URL. Alias a trace-branded custom domain to this project when one is available.
• Firebase (optional mirror): firebase/ hosts a static reserved page only. Do not add Auth/Firestore/Storage/Functions for the MVP.
• GitHub Pages (docs): apps/docs builds a fancy site from /docs and the docs-deploy.yml workflow publishes it to https://taxcollector23.github.io/trace/. Override the landing's docs link with VITE_DOCS_URL if needed.
• Homebrew tap: the formula lives in homebrew-trace/Formula/trace.rb, mirrored to TaxCollector23/homebrew-trace (tapped as TaxCollector23/trace, Homebrew's homebrew- prefix is implicit).

Security model

• The local daemon binds only to 127.0.0.1, never the local network.
• CORS is an explicit origin allow-list (the Vite dev server only), not a wildcard, a permissive policy on a localhost daemon able to trigger rollbacks would let any webpage the user has open script requests against it. Same-origin requests (the packaged app itself) don't need a CORS grant.
• No AI/LLM API key is ever required or stored. Every detection is deterministic pattern matching; no request path calls a model provider.
• Raw secrets are never stored; detected secrets are redacted at the point of detection.
• No cloud upload by default; project data stays on your machine.
• GitHub token (for trc github, trc ratify, and the CI action) is read-only, resolved from an env var / the gh CLI / ~/.trace/github.json, and only ever sent to api.github.com. Nothing is written back to GitHub.
• GitHub integration uploads only sanitized summaries, never raw files, secrets, or the local SQLite database.
• Git is required for reliable checkpoints and rollback.

See docs/security-model.mdx.

Limitations

• Full command guarding and run attribution require the trc run wrapper or supported hooks. GUI tools are otherwise observed only via file changes and Git diffs.
• Live agent feedback depends on the agent's hook surface. Claude Code, Cursor, OpenCode, and Codex can receive an enforced command decision through their supported hooks. Windsurf and the VS Code/Copilot bridge are observe-only for agent activity; Aider is available through the wrapper but is not part of trc integrations install all.
• Ratify reads a repo's PR files via a personal/CLI token, not a GitHub App, fine for local, user-triggered ratification; an org-wide automatic version would need App infrastructure this doesn't include.
• Cost is "unavailable" unless usage is routed through a proxy or imported.
• Rollback requires a Git repository.

See docs/limitations.mdx.

Engineering decisions

• UI library: the local dashboard uses a small custom CSS design system (no runtime UI dependency). It is already a serious developer-tool layout; Tailwind + shadcn/ui can be adopted later without changing the API.
• Diff viewer: a custom unified-diff renderer (no heavy dependency).
• Desktop shell: Tauri wrapping the existing dashboard build, no second UI to maintain.
• Analytics: none on the landing site by default.
• Code signing: not day-one; macOS/Windows may warn on downloaded binaries until notarization/signing is added.
• License: MIT.

Roadmap

• Live agent-feedback delivery for adapters beyond Claude Code, bounded by what each tool's own hook/plugin surface actually exposes
• GitHub App-based Ratify for org-wide, automatic PR checks
• Transparent local cost proxy for live token capture
• Signed release artifacts and notarized desktop builds
• Optional (explicitly requested) enterprise features: org policy files, central policy management, team dashboards, SSO, audit exports

License

MIT