Setup

This guide takes a repository from zero to a working repo-harness workflow: install the runtime, adopt the repo, wire your agent’s hooks, and confirm the guards fire.

Prerequisites

A git repository

repo-harness is repo-local. Run it from a git work tree — git init first if the folder isn’t one yet.

An agent

Claude Code or the Codex CLI as the executor. ChatGPT Pro is optional, for planning.

Bun

The CLI runs on Bun — the installer pulls it in if it’s missing. No Node setup required.

1. Install the CLI

Get the repo-harness binary onto your machine with whichever entry point fits:

curl

# macOS / Linux — installs Bun if missing, then the CLI
curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

bun

bun add -g repo-harness

npm

npm install -g repo-harness

Two different “installs”

The step above installs the CLI package. The next step, repo-harness init, is a separate action that configures the runtime on this machine. Same word, different jobs — that’s why the bootstrap command is init, not install.

2. Bootstrap the runtime

1. Run init once per machine. It’s idempotent — it wires the host hook adapters, the Waza skills, and the CodeGraph index for every project you’ll use:

   repo-harness init
   # ✓ host adapters · skills · CodeGraph configured

2. Check readiness any time (read-only):

   repo-harness status   # CLI version, host install state, route coverage
   repo-harness doctor   # PATH, version, hosts, trust state

Already bootstrapped?

repo-harness init is safe to re-run — use it to repair a half-configured machine. To pull a newer runtime later, use repo-harness update.

3. Adopt your repository

1. From the root of your repo, preview what will change. Nothing is written:

   repo-harness adopt --dry-run   # Migration Report

2. Apply the repo-local contract:

   repo-harness adopt

Adopt inspects the repo, installs the workflow files, wires the hooks, builds the CodeGraph index, and runs the workflow check. The tree it lays down:

• AGENTS.md Codex routing contract
• CLAUDE.md Claude Code routing contract
• Directory.ai/

  • Directoryharness/ contract, policy, checks, handoff

    • …
  • Directorycontext/ context-map + capabilities

    • …
  • Directoryhooks/ repo-local hook runtime

    • …
• Directorydocs/

  • spec.md product truth
• Directoryplans/ timestamped plan catalog

  • …
• Directorytasks/

  • Directorycontracts/ edit-scope authority

    • …
  • Directoryreviews/ completion gates

    • …
• Directoryscripts/ workflow helpers

  • …

Not a git repository?

Adopt refuses to run outside a git work tree. Run git init first, or pass an explicit target with repo-harness adopt --repo <path> for a non-git scaffold.

4. Wire your agent

init installs host adapters that dispatch editor events into repo-harness. Point your agent at them, then restart the session so the hooks load.

Claude Code

The adapter lives in your user settings — ~/.claude/settings.json — and routes every SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, and Stop event into the harness. Restart Claude Code to pick it up.

Codex

Codex reads ~/.codex/hooks.json. After init writes it, trust the hook config in Codex Settings — Codex won’t execute untrusted hooks. Then start a new session.

5. Verify it’s live

1. Prompt routing — submit any prompt. The UserPromptSubmit hook classifies intent and surfaces plan status in its advisory output.

2. The edit guard — ask the agent to edit a file before any plan is approved. The PreToolUse.edit guard fails closed and blocks the write until you capture a plan.

3. The workflow check — run the gate directly:

   bash scripts/check-task-workflow.sh --strict

A green check means the contract surface is consistent and the guards are armed.

6. Plan with ChatGPT Pro (optional)

Want ChatGPT Pro reading your plans without touching source? Expose only the workflow files through a local MCP sidecar:

repo-harness mcp setup chatgpt --repo .
repo-harness mcp serve --transport http \
  --host 127.0.0.1 --port 8765 --profile planner

Full details — including the read-only safety boundary — are on the ChatGPT Pro planner page.

Next steps

The workflow Plan → Sprint → Goal, and the Human Review Card.

Hooks The eight managed routes that guard and trace your work.

CLI reference Every command you'll reach for.