Checktrail

Checktrail

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

The local MCP server works through the chosen MCP host. That host handles AI selection and subscription/API authentication; Checktrail does not need to log in to a model service. Direct provider calls are an optional separate interface. See the MCP review workflow for implemented tools, planned review stages and the limits of fresh-session enforcement.

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. The explicit fetch-adapter command verifies every artifact in a pinned executable bundle before publishing a private file; registration and trusted execution are separate actions.

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.

The TypeScript check requires a local tsconfig.json and an installed compiler inside the configured root (project-local or hoisted to an ancestor). It disables noCheck, emission and incremental state. Every inventoried .ts, .tsx, .mts and .cts file in that project must appear in the compiler's file list. A clean compiler exit with excluded source is incomplete. Other compiler options, including strictness and declaration checking, come from the project config. Use javascript.typescript-build for project-reference solutions with fresh in-memory declarations. Vue SFC checking uses its separate adapter. TypeScript 6.0.3 is exercised in integration tests; other versions are unverified.

javascript.vue-router captures a selected native testing router and verifies complete record participation in declared URL probes; see the Vue Router profile for versions and projection limits. javascript.nuxt-runtime builds a fresh SSR testing assembly and checks native router capture after in-process requests. Opt-in version 2 also verifies native server handlers, middleware invocations, runtime config boundaries, generated API consumer types and controlled responses. See the Nuxt profile and assembly contracts for versions and scope limits. python.fastapi-routes captures a configured FastAPI application's native routes. Opt-in configuration version 2 also checks declared mounted/hosted assembly, security dependencies, response models, middleware/lifespan order and controlled ASGI responses. See the FastAPI profile and assembly contracts for versions and scope limits. python.django-routes captures supported nested URL resolv