Quickstart

Install Anatomia, run init in your repo, and ship a verified change. Two minutes to scaffold. Twenty minutes to your first proof.

Reading time · 8 minLast reviewed · 2026-07-02

Prerequisites

  • Node.js 22 or later
  • Git with user.name and user.email configured
  • A Git repository with at least one commit
  • Claude Code with an active subscription — needed for pipeline agents (Steps 3–4). The claude executable must be available on PATH. If you use stricter permission prompts, configure Claude Code flags after init.
  • GitHub CLI (gh) — used by Verify to create PRs after a passing run

Step 1: Install

bash
npm install -g anatomia-cli      # first install (or: npm update -g anatomia-cli)

Also available via pnpm add -g anatomia-cli or bun add -g anatomia-cli. This installs the ana command.

Step 2: Initialize

From inside your cloned repo:

bash
ana init

Init scans your project, detects your stack, and scaffolds the pipeline into your repo — agents, skills matched to your stack, and project context. Runs entirely on your machine. Your output will reflect your project:

terminal
✓ Scanned my-saas-app (3.2s)

  Stack:    TypeScript · Next.js · Prisma → PostgreSQL · Vitest
  Deploy:   Vercel

✓ Context → .ana/context/ (2 files)
✓ Skills → .ana/skills/ (7 skills)
  ✓ Cross-tool: CLAUDE.md + AGENTS.md

  Branch:   main
  Test:     pnpm run test -- --run
  Build:    pnpm run build

  Next:
    ana run             Start working (Ana knows your stack)
    ana run setup       Enrich with your team's knowledge (optional, ~10 min)
    ana init commit     Save to main ✓
Note

Verify detected commands. Init infers Test, Build, and Lint from your package.json. Override any command: ana config set commands.test "your-command". Monorepos with multiple surfaces: see Configurability for per-surface overrides.

Claude Code users can keep the default platform detection when Claude Code is the only installed host tool. To install both delivery paths, run ana init --platforms claude,codex.

Note

Optional but recommended: Run ana run setup to calibrate project knowledge (~10 min). Setup investigates your codebase, asks 2–3 questions, and writes rich context.

Persist to git

Init created files locally. Commit them to your artifact branch so every collaborator and agent session has the same context:

bash
ana init commit

This stages only infrastructure files (.ana/, .claude/, CLAUDE.md, AGENTS.md), commits with --no-verify, and pushes. Pipeline data and per-developer state are automatically excluded.

Run ana doctor to verify the installation is healthy — it checks CLI version, scan freshness, context quality, skill enrichment, proof chain status, and surfaces, plus an enforcement readout of the mechanical gates (test-evidence gate and process capture), in one dashboard.

Step 3: First pipeline run

Note

External services. If your project uses a database, Redis, or Docker containers, start them before running the pipeline — agents execute your test command as-is.

Describe a small change — a single-file fix or a feature you'd normally spend 30 minutes on.

bash
ana run

Start with a greeting — "hey Ana" — so the agent loads your project context before you describe the work. ana run dispatches to your configured platform: Claude Code projects start the Claude Code agents, and Codex projects open Codex with generated agent instructions.

For full platform setup, switching, and troubleshooting details, see Platform setup.

Ana investigates the codebase, surfaces tradeoffs, and writes a scope. You can scope several work items before building any of them — each runs through the pipeline independently. When you're ready to build, open a new terminal for each pipeline agent — agents must start fresh without state from previous runs:

  1. Plan: ana run plan — reads the scope, writes spec.md, and seals contract.yaml
  2. Build: ana run build — implements the spec, writes tests tagged to contract assertions
  3. Verify: ana run verify — independently verifies against the contract, writes findings, creates PR on pass
Note

Each agent runs CLI commands like ana work start and ana artifact save under the hood — managing worktrees, validating artifact structure, and computing integrity hashes. You don't run these manually.

If Verify finds issues, it produces a FAIL report. Run ana run build to fix, then ana run verify again. This is normal — 26 of Anatomia's own 213 proofs had rejection cycles.

Step 4: Review, merge, and complete

After Verify passes, it creates a PR. Review the PR — compare Build's report with Verify's findings. This is the moment the two independent accounts meet. When you're satisfied, merge the PR, then complete the work item:

bash
ana work complete <slug>

This archives the plan and writes a proof chain entry — assertions, findings, timing, and SHA-256 hashes of every artifact. The proof is a JSON record committed to your repo. It travels with the code.

View it:

bash
ana proof <slug>

You'll see the contract score, findings by severity, and timing per stage. Every assertion the contract defined, independently verified. The proof chain grows with every pipeline run — a permanent record of what was built, how it was verified, and what was found.

Updating

bash
npm update -g anatomia-cli    # update the CLI
ana init                      # refresh scan data + skill detection
ana init commit               # persist the refresh

Updating the CLI changes the binary only. Your agents, skills, context, and proof chain don't change until you run ana init. When you do, your rules, context files, and proof history are preserved — only machine-detected data refreshes. Run ana doctor after updating to confirm everything is healthy — it checks all six dimensions plus the enforcement readout in one command. ana work status will tell you when your project was initialized with an older version.

Next conceptThe pipelineFive stages, independence guarantees, and what each artifact proves.GuideReading a proofWhat each section of a proof page means.