Exhork is a local CLI that coordinates tools such as Codex, Claude Code, Gemini CLI, Ollama, and your own command-line providers. You choose who plans, who builds, and who reviews. Exhork handles the handoffs, verification, retry loop, and run history.

How It Works

flowchart LR
    T["Your task"] --> P["Planner"]
    P --> A["Advisor (optional)"]
    A --> B["Executor"]
    B --> V["Lint, test, build"]
    V --> R["Reviewer"]
    R -->|"PASS"| D["Done"]
    R -->|"NEEDS_WORK"| P

Each role can use a different AI subscription:

| Role | Responsibility | Typical permission | | --- | --- | --- | | Orchestrator | Plans architecture and prepares the handoff | Read-only | | Advisor | Challenges the plan or verification evidence | Read-only | | Executor | Edits files and runs implementation commands | Workspace write | | Reviewer | Checks correctness and decides whether to continue | Read-only |

For example, Codex can plan and review while Claude Code implements. A failed review returns concrete evidence to the next bounded iteration.

Quick Start

1. Open Your Project

Requirements: Node.js 20+, Git, and at least one authenticated AI CLI.

cd /path/to/your-project

2. Set Up Exhork

Run Exhork directly from npm. No clone, build, or global installation is required:

npx exhork@latest setup --full
npx exhork@latest doctor --suggest

setup --full detects the project, available AI tools, verification commands, package boundaries, and repository AI instructions. It creates exhork.config.yaml plus optional policy and playbook files without overwriting existing files.

3. Run a Task

npx exhork@latest run --pick --preflight --verify "Add CSV export to the reports page"

• --pick lets you choose the AI subscription for each role.
• --preflight checks provider commands and fallback chains first.
• --verify runs the project's inferred lint, test, and build commands before review.

For the shorter exhork command, install it globally once:

npm install --global exhork
exhork setup --full

Choose Your AI Team

Select every role for one run:

exhork run \
  --orchestrator codex-orchestrator \
  --executor claude-executor \
  --reviewer codex-reviewer \
  --preflight \
  --verify \
  "Implement the import flow"

Or save the combination as a reusable workflow:

exhork workflow create product-team \
  --orchestrator codex-orchestrator \
  --executor claude-executor \
  --advisors codex-reviewer \
  --reviewer codex-reviewer \
  --advisor-checkpoints pre-execute,post-verify \
  --activate

Useful built-in workflows:

| Workflow | Planner | Executor | Reviewer | | --- | --- | --- | --- | | codex-claude | Codex | Claude | Codex | | claude-codex | Claude | Codex | Claude | | all-codex | Codex | Codex | Codex | | all-claude | Claude | Claude | Claude | | dual-review | Codex | Claude | Codex + Claude |

Run exhork workflows to see the complete effective configuration.

What Exhork Saves

Every run produces inspectable evidence under .exhork/runs/<run-id>/:

flowchart TD
    R["Run directory"] --> H["handoff.md"]
    R --> O["Planner, executor, advisor, reviewer outputs"]
    R --> V["Verification results"]
    R --> G["Git before and after snapshots"]
    R --> E["Event log and timeline"]
    R --> P["report.md"]

Use these commands to inspect the result:

exhork runs
exhork dashboard
exhork report <run-dir>
exhork timeline <run-dir>
exhork diff <run-dir>

Interrupted work can continue with exhork resume <run-dir>. A plan can also be handed to an external AI or human with dispatch, then returned to Exhork with attach for verification and review.

Safety Defaults

• Planner, advisor, and reviewer profiles are read-only by default.
• Only executor profiles declare workspace-write capability.
• A workspace lease prevents two Exhork loops from editing the same checkout.
• exhork isolate can run higher-risk work in a dedicated branch and Git worktree.
• Target scope and secret guards run before review.
• Read-only advisor and reviewer ensembles may run in parallel; write-capable or unknown providers run sequentially.

Provider CLIs still perform the actual work, so review provider permissions before using Exhork on sensitive repositories.

Common Commands

| Command | Use it to | | --- | --- | | exhork setup --full | Adopt Exhork in an existing repository | | exhork doctor --suggest | Check installed AI tools and suggest a workflow | | exhork ready | Validate config, policy, providers, and project setup | | exhork route "task" | Recommend a workflow, target, and checks | | exhork run "task" | Run the complete orchestration loop | | exhork plan "task" | Create a plan without executing it | | exhork review "focus" | Review current changes without implementing | | exhork isolate "task" | Run safely in a separate worktree | | exhork next | Show the next recommended operator action | | exhork --help | Show all commands |

Migrating Existing Projects

Exhork prefers the new exhork command, .exhork/ artifact directory, and exhork.*.yaml filenames. Existing agent-orch commands and configuration filenames remain supported as migration aliases. Legacy configs that omit an artifact directory continue to use .agent-orch/runs so existing history stays visible.

New setup and generated commands always use the Exhork names.

More Detail

• Repository AI instructions
• Parallel advisor and reviewer ensembles
• Contributing
• Release process
• Security policy

Development

npm ci
npm run ci
npm run release:dry

npm run ci type-checks, tests, builds, and installs the packed CLI into a clean project. npm run release:dry also verifies the final npm package contents.