Checktrail

Local code validation with a CLI, MCP tools, and evidence of what actually ran.

Formerly Repo Verifier. See the rename guide for existing source checkouts.

Published preview: 0.1.0-alpha.5. Public source is available at stsepelin/checktrail. See implementation status, the plan and the language matrix before relying on an adapter. Installation covers the CLI, Claude Code and Codex. Agent skills provides setup, validation and review workflows installable with npx skills add stsepelin/checktrail. Project setup covers init, doctor and MCP configuration generator. Release preparation records publication and verification gates. The milestone audit separates implemented profiles from open acceptance work; client checks record actual application coverage. Public adoption records the published package on five pinned libraries, including setup friction and compatibility gaps. Alpha.3 fixes the recorded TypeScript 4.9.5 incompatibility. The setup scope guide explains language, documentation and workflow coverage. Alpha.5 adds named Go build-tag profiles with per-check exclusions. Its release record includes package, client and upgrade/rollback verification.

The hosted matrix passed at release commit 832a044 on Linux and macOS. The exact npm tarball and fresh CLI/MCP installations were verified. The MCP Registry entry is active; execution remains disabled by default.

Checktrail discovers projects, plans registered checks, invokes native tools when explicitly trusted, and reports results without turning skipped or empty checks into success. The same engine serves developers, CI and MCP clients.

The optional library task store retains local validation results across restarts. A library worker adds native execution, polling and cancellation. MCP reports still use memory; standard Tasks integration remains pending.

Try the local checkout

Requires Node.js 22 or newer. Execution currently targets macOS and Linux.

npm ci --ignore-scripts
npm run build
node dist/src/cli.js plan --root examples/javascript --detailed
node dist/src/cli.js run --root examples/javascript --trust-project --detailed

plan and inspect read files without executing project code. run requires --trust-project: tests, compiler plugins and project configuration can execute code with your user privileges. This is not a sandbox.

Successful commands return JSON except help/version; input errors use stderr. Exit codes:

A passing run applies to the selected checks and scope only. PHP syntax passing does not imply its application tests passed. Unknown frameworks and empty plans are incomplete. A source change during validation prevents an aggregate pass.

Initial adapters

Tools must already be installed. No dependency installation, automatic fixes, service startup, migrations, commits or deployments are performed by the engine. Go execution disables module proxy downloads and toolchain auto-downloads. The Rust profile uses locked offline Cargo and disables rustup auto-installation. Other invoked tools and test code can still access the network.

Select checks

Without configuration, registered defaults apply to each detected project. Node tests are selected automatically only for the exact script node --test. Python needs an explicit selection because a manifest does not identify a runner. Create checktrail.json in the inspected root:

{
  "schemaVersion": 1,
  "projects": [
    { "path": "web", "checks": ["javascript.node-test", "javascript.eslint"] },
    { "path": "library", "checks": ["javascript.typescript"] },
    { "path": "service", "checks": ["go.format", "go.vet", "go.test"] },
    { "path": "worker", "checks": ["python.unittest"] }
  ]
}

When present, this file selects only the listed projects/checks. Paths are exact discovered project roots relative to --root; use . for that root itself. Configuration cannot supply arbitrary commands or enable execution permissions. The schema rejects unknown fields and check IDs are validated by the engine. Private configuration and rules need not be published. Local public/private JSON packs and additive operator overlays are implemented; see policy packs. An explicit fetch-pack command can download a pinned data-only pack over HTTPS for later offline use.

Operator-registered external adapters can run a pinned local Node, Python, PHP or native executable bundle. Repository configuration can select their registered checks; execution still requires operator trust. The protocol checks evidence completeness, while the adapter author remains responsible for the correctness of its analysis.