harnesses

Community harness kit for Claude Code — multi-agent orchestration with 7 patterns and 8 specialist teams.

한국어 문서

Install

npm install -g harnesses

Note: npx harnesses does not work on npm 10+ due to changed binary resolution. Use global install.

Claude Code (default)

harnesses                  # install all teams to ~/.claude/
harnesses --claude         # same, explicit
harnesses be-team fe-team  # specific teams only

Agents and skills are installed to ~/.claude/agents/ and ~/.claude/commands/.

Codex / OpenAI

harnesses --codex          # installs codex-harnesses + Codex auto-routing plugin

Requires Python 3.11+ and uv (recommended) or pip3. After install:

codex-harnesses route "Redis vs Memcached 결정해줘" --json
codex-harnesses run "Review this PR for correctness and security"
codex-harnesses "PostgreSQL vs MongoDB?" --option-a PostgreSQL --option-b MongoDB

The Codex package ships native routing for debate, explore, review, and research teams. The installed Codex plugin teaches Codex to auto-route natural-language requests such as Redis vs Memcached 결정해줘 to the right harness, while /debate remains available as an explicit slash command.

Teams

| Team | Pattern | Agents | Skills | Use when | |------|---------|:------:|:------:|----------| | dev-team | Pipeline | 5 | 1 | Building a full feature (FE + BE + review + QA) | | review-team | Fan-out/Fan-in | 6 | 2 | Auditing existing code, a PR, or full codebase | | fe-team | Expert Pool + Reflection | 6 | 5 | React, Next.js, Tailwind, a11y, perf | | be-team | Pipeline + Expert Pool + Reflection | 8 | 5 | Hono/Express API, LLM integration, MCP | | explore-team | Hierarchical Delegation | 4 | 3 | Investigating codebase, root cause, arch review | | research-team | Blackboard | 4 | 3 | Web research, library comparison, fact-gathering | | debate-team | Adversarial Debate | 4 | 2 | Architecture decisions, trade-off analysis | | ops-team | Skills + Hooks | 0 | 3 | Release, CI watch, orphan process cleanup |

Patterns

| # | Pattern | Description | |---|---------|-------------| | 1 | Pipeline | Sequential stages — each stage's output feeds the next | | 2 | Fan-out / Fan-in | Parallel workers, results aggregated by a moderator | | 3 | Expert Pool | Route to domain specialist agent | | 4 | Hybrid Pipeline + Expert Pool | Sequential stages, each stage is an expert | | 5 | Hierarchical Delegation | Scout orchestrates, delegates to specialists | | 6 | Adversarial Debate | Advocates argue positions, judge decides (max 5 rounds) | | 7 | Blackboard | Shared state file; agents read/write with no explicit handoff |

Cross-cutting: Reflection Loop, Circuit Breaker, Escalation, Consensus Voting.

See docs/PATTERNS.md for full details.

Repository layers

| Layer | Path | Purpose | |-------|------|---------| | Core | core/ | Shared orchestration pattern specs, routing schema, run state schema, blackboard schema, and trace schema | | Claude Code | claudecode/plugins/ | Claude Code teams, agents, skills, hooks, and harness docs | | Codex | codex/ | Python package that orchestrates Codex CLI workers |

The npm CLI in bin/install.mjs is the distribution wrapper: by default it installs the Claude Code layer to ~/.claude/; with --codex it installs the Codex Python package, slash prompts, and auto-routing plugin.

Layout note: Since 1.0.3, Claude Code plugins live under claudecode/plugins/ instead of the old root-level plugins/ directory. Existing installed teams still use the same ~/.claude/ destination paths; only the repository layout changed.

Usage

Skills (slash commands)

# Frontend work
/fe-component "UserCard with avatar and role badge"
/fe-page "Dashboard with stats and recent activity"

# Backend work
/be-api "POST /invoices with Zod validation"
/be-mcp-server "GitHub integration MCP server"

# Review
/review-code src/auth/middleware.ts
/review-codebase src/ --screeners 5    # full codebase, 5 parallel screeners

# Research
/research-web "Compare Zustand vs Jotai for Next.js 15"

# Debate
/debate-tradeoff "SSR vs SPA for internal dashboard"

# Operations
/zombie-collector     # clean orphan processes
/release              # release workflow
/ci-watch             # monitor CI run

Routing

Claude Code routes your request to the right team automatically based on triggers in CLAUDE.md. You can also be explicit:

"explore로 이 버그 조사해줘"
"review-team으로 PR #42 리뷰해"
"debate-team: Redis vs Memcached 결정해줘"

Examples

See examples/ for 5 real-world walkthroughs:

1. Simple CRUD feature — dev-team
2. Code review — review-team (SARIF output)
3. Research task — research-team (Blackboard flow)
4. Architecture decision — debate-team
5. Debugging + cleanup — explore-team → ops-team

Uninstall

harnesses --uninstall           # Claude Code: remove from ~/.claude/
uv tool uninstall codex-harnesses  # Codex: remove Python package

Creating custom teams

See docs/CREATING_TEAMS.md.

License

MIT — justn-hyeok