claude-forge-plugin

   

Multi-CLI delegation and orchestration for Claude Code.

Route backend work to Codex CLI (GPT-5.3, 128K) and frontend work to Gemini CLI (1M context). Claude orchestrates everything — classifying tasks, delegating to the right model, and verifying results.

No CLIs required. Built-in agents handle it when CLIs aren't installed.

Install

npm install -g claude-forge-plugin

Or as a Claude Code plugin:

/plugin marketplace add https://github.com/staticpayload/claude-forge
/plugin install claude-forge

Then run the setup wizard:

/claude-forge:setup

The wizard handles CLI detection, model preferences, HUD configuration, and team setup. Already configured? It offers a quick CLAUDE.md update instead of the full wizard.

How it works

Your prompt hits a keyword router (100+ patterns). It classifies the task, scores complexity, and routes to the right destination.

prompt → keyword router → classification
                            ├── Codex CLI    (backend signals: api, server, database, auth...)
                            ├── Gemini CLI   (frontend signals: component, ui, css, react...)
                            ├── built-in agents  (when CLIs unavailable)
                            └── direct execution (simple tasks)

Complexity scoring decides the model tier: Haiku for simple work, Sonnet for standard, Opus for architecture.

Teams

Coordinated multi-agent teams using Claude Code native infrastructure. The flagship orchestration feature.

/claude-forge:team 4 "build the user dashboard with auth, API, components, and tests"

          ┌─────────────────────────────────────────┐
          │              TEAM LEAD                   │
          │   decompose → route → monitor → verify   │
          └──────┬──────────┬──────────┬─────────────┘
                 │          │          │
         ┌───────▼──┐ ┌────▼─────┐ ┌──▼────────┐
         │ Worker 1  │ │ Worker 2 │ │ Worker 3  │
         │ executor  │ │ designer │ │ codex MCP │
         │ (claude)  │ │ (claude) │ │ (GPT-5.3) │
         └───────────┘ └──────────┘ └───────────┘

Workers communicate directly, claim tasks from a shared list, and respect file ownership boundaries.

Smart auto-routing classifies each subtask and sends it to the best provider — Codex for backend, Gemini for frontend, Claude agents for everything else. No manual routing needed.

What makes it different

Feature	claude-forge	Others
Worker-to-worker messaging	Peer-to-peer	Lead-only
Task routing	Automatic per-subtask	Manual
Dynamic scaling	Early finishers reassigned	Fixed
Cascade mode	Auto-create test + review tasks	None
Cross-CLI verification	Alternate model reviews work	None
Team templates	5 pre-built	None
Build step required	No	Yes

Templates

Start fast with pre-built team compositions:

Template	Workers	Use case
build-team	architect + executor + designer	Feature development
review-team	style + quality + security + perf	Code review
fullstack-team	architect + executor + designer + test-engineer	End-to-end features
audit-team	security + quality + code reviewers	Security audit
debug-team	explorer + debugger + executor	Bug investigation

/claude-forge:team fullstack-team "implement the billing system"

Full teams documentation →

Swarm

Lightweight fire-and-forget parallel execution. No team overhead — just spawn agents and collect results.

/claude-forge:swarm 5 "write unit tests for each service in src/services/"

Swarm decomposes the task, routes each subtask to the best provider, spawns all agents immediately, and reports results. Wave-based spawning handles 5+ tasks without hitting concurrency limits.

Use team when tasks need coordination. Use swarm when they're independent.

Full swarm documentation →

Execution Modes

9 modes that compose together. Full guide →

Mode	Trigger	Description
autopilot	"autopilot", "build me"	Full pipeline — expand, plan, execute, QA, validate
ralph	"ralph", "don't stop"	Persistence loop — work, verify, repeat until done
ultrawork	"ulw", "ultrawork"	Parallel engine — decompose, assign ownership, run simultaneously
ecomode	"ecomode", "budget"	Cost-efficient model routing — Haiku/Sonnet preference
ultraqa	"ultraqa"	QA cycling — test, diagnose, fix, repeat
ultrapilot	"ultrapilot"	Parallel autopilot with file ownership partitioning
team	"forge team", template names	Coordinated agents with shared task list
swarm	"swarm", "fire and forget"	Fire-and-forget parallel execution
pipeline	"pipeline", "chain agents"	Sequential agent chains with data passing

Ralph includes ultrawork. Ecomode modifies any mode. Autopilot transitions to ralph or ultraqa.

Skills

42+ skills across 8 categories. Trigger them naturally or with /claude-forge:<skill>.

CLI delegation

Skill	Description
forge	Auto-route to best CLI by signal classification
backend / frontend	Direct delegation to Codex or Gemini
backend-agent / frontend-agent	Built-in agents when CLIs unavailable
review	Parallel review — Codex checks logic, Gemini checks design
parallel	Decompose task into parallel waves across both CLIs

Planning and research

Skill	Description
plan	Strategic planning with interview, consensus, or review modes
research	Parallel scientists — sub-questions, cross-validation, synthesis

Code quality

Skill	Description
code-review	5-dimension severity-rated review
security-review	OWASP Top 10, secrets detection, auth audit
tdd	Red-Green-Refactor enforcement
build-fix	Minimal-diff fixes for build errors

Analysis

Skill	Description
analyze	Deep investigation — architecture, bugs, performance
deepsearch	Multi-strategy exhaustive codebase search

Productivity, specialists, and configuration

Productivity: worktree · techdebt · fix · learn · deepinit · note · learner · trace

Specialists: frontend-ui-ux · git-master

Configuration: setup · doctor · help · hud · cancel · set-codex-model · set-gemini-model · enable-codex · enable-gemini

Magic keywords

Say these naturally in any prompt. They compose together.

Keyword	Effect
ultrawork / ulw	Maximum parallelism — decompose and run agents simultaneously
deepsearch	Exhaustive search — multiple strategies, never stops at first result
analyze / investigate	Deep context gathering before any action
ultrathink / think hard	Extended reasoning — quality over speed

"ultrawork this analysis" activates both parallel execution and deep investigation.

Agents

32 agents with automatic model routing. Full catalog →

Lane	Agents
Build	explorer · analyst · planner · architect · debugger · executor · deep-executor · verifier
Review	style-reviewer · quality-reviewer · api-reviewer · security-reviewer · performance-reviewer · code-reviewer
Domain	dependency-expert · test-engineer · build-fixer · designer · writer · qa-tester · scientist · git-master · quality-strategist
Product	product-manager · ux-researcher · information-architect · product-analyst
Coordination	critic · vision · researcher · team-lead · team-worker

Team compositions

Feature:    analyst → planner → executor → test-engineer → quality-reviewer → verifier
Bug fix:    explorer + debugger → executor → test-engineer → verifier
Review:     style-reviewer + quality-reviewer + api-reviewer + security-reviewer
Full-stack: planner → [Codex: backend] + [Gemini: frontend] → test-engineer → verifier

HUD

Two-line status bar showing everything at a glance.

branch:main | model:Claude Opus 4
[FORGE] | 5h:[████████]42% wk:[████░░░░]28% | cx:✓ gm:✓ | run:cx:1 done:3 | ~$0.18 | ctx:[██████░░░░]62%

Rate limits, CLI availability, active jobs, cost estimate, context usage. Configure with /claude-forge:hud.

Architecture

Two MCP servers handle CLI delegation. Full guide →

forge-codex — Spawns codex exec --yolo via stdin. GPT-5.3, 128K context. Tools: codex_exec · codex_status · codex_cancel · codex_list

forge-gemini — Spawns gemini -y via stdin. Gemini 3 Pro, 1M context. Tools: gemini_exec · gemini_status · gemini_cancel · gemini_list

Five lifecycle hooks: SessionStart (CLI detection) · UserPromptSubmit (keyword routing) · PreToolUse (per-tool hints) · PostToolUse (context monitoring) · Stop (continuation enforcement)

Security: path-validated context files, system directory blocklist, basename-only CLI resolution, anti-loop sandwich pattern, 10MB output cap.

File structure

claude-forge/
├── .claude-plugin/
│   ├── plugin.json
│   └── marketplace.json
├── agents/                  32 agent system prompts
│   ├── team-lead.md         team coordinator (opus)
│   └── team-worker.md       team worker (sonnet)
├── docs/                    feature documentation
│   ├── teams.md
│   ├── swarm.md
│   ├── modes.md
│   ├── agents.md
│   └── cli-delegation.md
├── hooks/hooks.json         5 lifecycle hooks
├── hud/
│   ├── forge-hud.mjs        status bar renderer
│   └── usage-api.mjs        Anthropic Usage API
├── scripts/
│   ├── keyword-router.mjs   100+ regex patterns
│   ├── session-init.mjs     CLI detection
│   ├── context-monitor.mjs  token tracking
│   ├── pre-tool-enforcer.mjs
│   ├── continuation.mjs     exit prevention
│   └── lib/                 routing, keywords, complexity
├── servers/
│   ├── codex-server.mjs     Codex MCP server
│   └── gemini-server.mjs    Gemini MCP server
├── skills/                  42+ skill definitions
│   ├── team/SKILL.md        1600 lines — teams orchestration
│   ├── swarm/SKILL.md       fire-and-forget parallel
│   └── ...
└── templates/CLAUDE.md      injected instructions

Documentation

Guide	Description
Teams	Coordinated multi-agent teams — templates, lifecycle, smart routing, cascade
Swarm	Fire-and-forget parallel execution — wave spawning, routing
Execution Modes	All 9 modes — autopilot, ralph, ultrawork, teams, and more
Agents	Full catalog of 32 agents — models, capabilities, compositions
CLI Delegation	Codex and Gemini integration — routing, MCP tools, fallbacks

Examples

autopilot: Build user auth with JWT, password hashing, rate limiting, and email verification

forge team fullstack-team: Implement the entire checkout flow with Stripe integration

swarm 5: Write comprehensive tests for every module in src/services/

ultrawork: Migrate the entire codebase from CommonJS to ESM

forge review the authentication PR

ecomode: Add form validation to the signup page

Troubleshooting

Codex CLI not found — npm install -g @openai/codex then /claude-forge:enable-codex

Gemini CLI not found — npm install -g @google/gemini-cli then /claude-forge:enable-gemini

Skills not appearing — Run /claude-forge:doctor for 7 diagnostic checks with auto-fix

Cancel a stuck mode — /claude-forge:cancel --force

Contributing

Pure ESM JavaScript, no build step. Add a skill by creating skills/<name>/SKILL.md, adding trigger patterns to keyword-router.mjs, and updating templates/CLAUDE.md.

_{GPL-3.0 · GitHub · npm · Issues}