Help & Documentation

Everything you need to know about using CodeChecks.

1Getting Started

CodeChecks follows a structured four-step workflow:

  1. Submit requirements — Describe what you want to build. Include your tech stack (e.g., Next.js, React, Node), constraints (e.g., “do not modify existing tests”), and acceptance criteria.
  2. Review the plan — The AI Planner analyzes your requirements and generates a task list with file plans and verification commands. Review the plan before proceeding.
  3. Implement tasks — Select a task and provide the contents of relevant files. The AI Implementer generates a unified diff (code patch) for that task.
  4. Verify — Run the suggested verification commands (e.g.,npx tsc --noEmit,npm run build), paste the output, and submit for automated verification analysis.

2Verification Commands

Every plan includes baseline verification commands that must pass before a task is considered complete:

npx tsc --noEmit

Runs the TypeScript compiler without emitting files. Catches type errors, missing imports, and interface mismatches. Only included for TypeScript projects (when tsconfig.json exists).

npm run build

Runs the project's build script. For Next.js apps, this compiles all pages and API routes, catching runtime issues like missing modules or invalid configurations.

Task-specific verification commands (e.g., test scripts) are added on top of these baselines by the Planner.

3Policy Enforcement

CodeChecks enforces two protection policies to prevent accidental modifications to critical files:

Dependency Policy

Modifications to package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, .npmrc, and .yarnrc.yml are blocked by default.

To allow: add [ALLOW_DEPS] to your acceptance criteria.

Sensitive File Policy

Modifications to environment files (.env.*), authentication modules, middleware, and files containing payment, billing, stripe, secret, or credential in their paths are blocked by default.

To allow: add [ALLOW_SENSITIVE] to your acceptance criteria.

4Evidence Bundles

Every CodeChecks run produces a JSON evidence record stored in the.codecheck/evidence/ directory. Each record includes:

  • Repo SHA — the git commit hash at the time of generation
  • Patch hash — SHA-256 of the generated diff
  • Verification commands — what was run and the results
  • Environment info — Node version, npm version, OS, lockfile hash
  • Provider metadata — which model was used, latency, fallback status
  • Reproduce instructions — step-by-step commands to recreate the run

Evidence bundles are excluded from git by default (via .gitignore).

5Troubleshooting

Provider failures (403, 429, 5xx)

CodeChecks automatically retries transient errors with exponential backoff. If the primary model fails persistently, it falls back to a secondary model. Check the error message for details — a 403 usually means an API key permission issue.

Parse errors

If the AI output can't be parsed, CodeChecks retries once with stricter prompting. If it still fails, try simplifying your requirements or breaking them into smaller tasks.

Policy violation errors

If you see “dependency policy violation” or “sensitive file policy violation,” the generated code tried to modify a protected file. Add the appropriate policy flag ([ALLOW_DEPS] or [ALLOW_SENSITIVE]) to your acceptance criteria if the modification is intentional.

Needs more files

If the Implementer requests additional file contents, CodeChecks attempts to read them from your project automatically and retries. If that fails, you may need to provide the file contents manually.