---
title: Quickstart
description: Install Anatomia, run init in your repo, and ship a verified change. Two minutes to scaffold. Twenty minutes to your first proof.
readingTime: 8
---

## Prerequisites

- Node.js 22 or later
- Git with `user.name` and `user.email` configured
- A Git repository with at least one commit

<ForPlatform platform="claude-code">
- [Claude Code](https://claude.ai/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.
</ForPlatform>

<ForPlatform platform="codex">
- [Codex](https://openai.com/index/introducing-codex/) — needed for pipeline agents (Steps 3–4). The `codex` executable must be available on PATH. Codex projects use generated `.codex/agents/*.agent.toml` manifests for agent delivery.
</ForPlatform>

- [GitHub CLI](https://cli.github.com/) (`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:

<div style={{background:"var(--bg-card)",border:"1px solid var(--border)",borderRadius:"var(--radius-md)",margin:"8px 0 18px",fontFamily:"var(--font-mono)",fontSize:"12.5px",lineHeight:1.65,overflow:"hidden"}}>
<div style={{display:"flex",alignItems:"center",justifyContent:"space-between",padding:"8px 14px",borderBottom:"1px solid var(--hairline)",background:"var(--bg-elev)",fontSize:"11px",color:"var(--ink-60)"}}>
<span style={{color:"var(--ink-45)",textTransform:"uppercase",letterSpacing:"0.06em",fontSize:"10px"}}>terminal</span>
</div>
<pre style={{padding:"14px 16px",color:"var(--ink-75)",overflowX:"auto",whiteSpace:"pre",margin:0,background:"transparent",fontSize:"inherit",lineHeight:"inherit",fontFamily:"inherit"}}>
<span style={{color:"var(--pass)"}}>✓</span>{" Scanned my-saas-app "}<span style={{color:"var(--ink-45)"}}>{"(3.2s)"}</span>{"\n\n"}{"  "}<span style={{color:"var(--brand-light)"}}>Stack:</span>{"    TypeScript · Next.js · Prisma → PostgreSQL · Vitest\n"}{"  "}<span style={{color:"var(--brand-light)"}}>Deploy:</span>{"   Vercel\n\n"}<span style={{color:"var(--pass)"}}>✓</span>{" Context → .ana/context/ (2 files)\n"}<span style={{color:"var(--pass)"}}>✓</span>{" Skills → .ana/skills/ (7 skills)\n"}{"  "}<span style={{color:"var(--pass)"}}>✓</span>{" Cross-tool: CLAUDE.md + AGENTS.md\n\n"}{"  "}<span style={{color:"var(--brand-light)"}}>Branch:</span>{"   main\n"}{"  "}<span style={{color:"var(--brand-light)"}}>Test:</span>{"     pnpm run test -- --run\n"}{"  "}<span style={{color:"var(--brand-light)"}}>Build:</span>{"    pnpm run build\n\n"}{"  "}<span style={{color:"var(--brand-light)"}}>Next:</span>{"\n"}{"    "}<span style={{color:"var(--info)"}}>ana run</span>{"             Start working (Ana knows your stack)\n"}{"    "}<span style={{color:"var(--info)"}}>ana run setup</span>{"       Enrich with your team's knowledge (optional, ~10 min)\n"}{"    "}<span style={{color:"var(--info)"}}>ana init commit</span>{"     Save to main ✓"}
</pre>
</div>

<Callout variant="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](/docs/guides/configurability) for per-surface overrides.
</Callout>

<ForPlatform platform="claude-code">
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`.
</ForPlatform>

<ForPlatform platform="codex">
Codex users can select Codex explicitly during setup with `ana init --platforms codex`, or install both delivery paths with `ana init --platforms claude,codex`.
</ForPlatform>

<Callout variant="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.
</Callout>

### 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, and proof chain status in one dashboard.

## Step 3: First pipeline run

<Callout variant="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.
</Callout>

Describe a small change — a single-file fix or a feature you&apos;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](/docs/guides/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

<Callout variant="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.
</Callout>

If Verify finds issues, it produces a FAIL report. Run `ana run build` to fix, then `ana run verify` again. This is normal — <DocsStat value="rejections" /> of Anatomia&apos;s own <DocsStat value="proofCount" /> 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 five dimensions in one command. `ana work status` will tell you when your project was initialized with an older version.

<NextCards cards={[
  {
    eyebrow: "Next concept",
    title: "The pipeline",
    href: "/docs/concepts/pipeline",
    description: "Five stages, independence guarantees, and what each artifact proves."
  },
  {
    eyebrow: "Guide",
    title: "Reading a proof",
    href: "/docs/guides/reading-a-proof",
    description: "What each section of a proof page means."
  }
]} />
