claude-forge-plugin

Route backend to Codex CLI (GPT-5.3) • Frontend to Gemini CLI (1M context) • Claude orchestrates everything

Quick Start   |   Skills   |   Examples   |   Architecture

🤔 Why claude-forge?

Without forge 🧠 Claude works alone ⏳ Sequential execution 📐 200K context only 👁️ Single review perspective 🤞 Manual task routing

With forge 🔥 Three AI models working in parallel ⚡ Up to 5 simultaneous agents 🔭 200K + 128K + 1M context combined 🔍 Multi-model cross-review 🎯 Automatic classification & routing

The core idea: Claude Code becomes the orchestrator. It reads your codebase, understands your intent, classifies the task, and delegates to the right specialist — Codex for backend, Gemini for frontend, or both in parallel.

⚡ Quick Start

# 1. Add the marketplace
/plugin marketplace add https://github.com/staticpayload/claude-forge

# 2. Install
/plugin install claude-forge

# 3. One-time setup
/claude-forge:setup

Then try:

"forge this: build a REST API for user authentication with JWT"

💡 No CLIs needed — forge works with Claude's built-in agents. Install Codex CLI and/or Gemini CLI later for full delegation power.

🔮 How It Works

flowchart TD
    A["🗣️ Your Prompt"] --> B["🔀 Keyword Router"]
    B --> |"Skill match"| C["🛠️ 42 Skills"]
    B --> |"Signal words"| D["🎯 Auto-Classify"]
    B --> |"Simple task"| E["⚡ Direct"]

    C --> F["🤖 Codex CLI\n(Backend)"]
    C --> G["✨ Gemini CLI\n(Frontend)"]
    C --> H["🧩 Built-in\nAgents"]
    D --> F
    D --> G

    style A fill:#1f6feb,stroke:#58a6ff,color:#fff
    style B fill:#8250df,stroke:#bc8cff,color:#fff
    style C fill:#bf3989,stroke:#f778ba,color:#fff
    style D fill:#bf3989,stroke:#f778ba,color:#fff
    style E fill:#57606a,stroke:#8b949e,color:#fff
    style F fill:#da3633,stroke:#ff7b72,color:#fff
    style G fill:#1a7f37,stroke:#3fb950,color:#fff
    style H fill:#9a6700,stroke:#d29922,color:#fff

🔀	Keyword Router — 95 regex patterns classify every prompt
🪄	Magic Keywords — say "ultrawork" or "think hard" to inject enhanced behavior
🎯	Auto-Classification — detects backend/frontend signal words for routing
📊	Complexity Scoring — routes to Haiku (simple), Sonnet (medium), or Opus (complex)

📦 Skills Reference

🚀 Execution Modes

The big five. Persistent modes that change how Claude operates.

	Skill	Trigger	What happens
🤖	autopilot	"autopilot", "build me"	Full pipeline: expand → plan → execute → QA → validate. 5 phases, resumable.
🪨	ralph	"ralph", "don't stop"	Persistence loop. Work → verify → repeat until done. Max 10 iterations.
⚡	ultrawork	"ultrawork", "ulw"	Parallel engine. Decompose → assign ownership → run simultaneously.
💰	ecomode	"ecomode", "budget"	Haiku for simple, Sonnet for medium, Opus when needed. 3-5x cheaper.
🧪	ultraqa	"ultraqa"	QA cycling: test → diagnose → fix → repeat. Max 5 cycles.

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

🎭 Orchestration — Multi-agent coordination

	Skill	Trigger	What happens
🚄	ultrapilot	"ultrapilot"	Parallel autopilot. Architect decomposes, 5 workers, file ownership.
👥	team	"forge team"	N agents on shared task list with file ownership.
🔗	pipeline	"pipeline"	Sequential chains with data passing. 6 presets.

🧠 Planning & Research

	Skill	Trigger	What happens
📋	plan	"plan this"	4 modes: interview, direct, consensus (3 architects), review (critic).
🔬	research	"research this"	Parallel scientists. 3-7 sub-questions, cross-validate, synthesize.

🔧 CLI Delegation — Direct routing control

	Skill	Trigger	What happens
🎯	forge	"forge this"	Auto-route by signal classification
🔍	review	"forge review"	Parallel: Codex (logic) + Gemini (design)
⬛	backend	"use codex"	Direct Codex delegation
🟩	frontend	"use gemini"	Direct Gemini delegation
🔲	backend-agent	"backend agent"	Claude agents (no CLI)
🟢	frontend-agent	"frontend agent"	Claude agents (no CLI)
⚡	parallel	"forge parallel"	Decompose + parallel waves

✅ Code Quality — Reviews, testing, standards

	Skill	Trigger	What happens
🔎	code-review	"code review"	5-dimension review, severity-rated findings
🛡️	security-review	"security review"	OWASP Top 10 mapping, remediation priorities
🔴	tdd	"tdd", "test first"	Red-Green-Refactor enforcement
🔨	build-fix	"build-fix"	Minimal-diff fixing, stops when green

🔬 Analysis — Deep investigation

	Skill	Trigger	What happens
🧬	analyze	"forge analyze"	Architecture, bug, performance, dependency analysis
🌊	deepsearch	"deepsearch"	Exhaustive multi-strategy codebase search

⚙️ Productivity — 8 daily workflow tools

Skill	What it does
worktree	Git worktree manager for parallel feature development
techdebt	Scan duplicates, dead exports, unused deps, stale TODOs
fix	Auto-fix from CI logs, test failures, Docker errors
learn	Auto-update CLAUDE.md with project patterns
deepinit	Generate hierarchical AGENTS.md for entire codebase
note	Persistent notepad: priority, working (7-day), manual
learner	Extract reusable skills from hard-won debugging
trace	Visualize execution timeline and stats

🎨 Specialists & ⚙️ Configuration

Specialists: frontend-ui-ux (Gemini/designer, WCAG 2.1) • git-master (atomic commits, style detection)

Config: setup • set-codex-model • set-gemini-model • enable-codex • enable-gemini • hud • doctor (7 checks) • help • cancel (--force)

🪄 Magic Keywords

Say these naturally in any prompt — they compose together.

⚡ ultrawork ulw Maximum parallelism. Decompose & run agents simultaneously.

🔍 search deepsearch Exhaustive search. Multiple strategies, never stops at first result.

🧠 analyze investigate Deep context gathering before any action. Read everything first.

💭 ultrathink think hard Extended reasoning. Quality over speed. Consider all angles.

💡 Tip: Combine them — "ultrawork this analysis" activates both parallel execution and deep investigation.

📊 Intelligent Features

🎯 Automatic Task Routing

Backend signals → Codex: api endpoint server database sql migration cli script pipeline docker auth middleware cache redis queue worker webhook microservice

Frontend signals → Gemini: component ui ux css style layout react vue svelte html design theme animation accessibility tailwind visual mobile

📈 Complexity Scoring — 0-15+ scale for model routing

Signal	Weight
Architecture decisions	+3
System-wide impact	+3
Multiple subtasks	+3
Debugging / Risk / Refactoring	+2 each
Cross-file changes	+2

0-3 → Haiku    4-8 → Sonnet    8+ → Opus

🧩 Task Decomposition — Parallel execution waves

• Type detection → fullstack, refactoring, bug-fix, feature, testing, docs, infra
• Area extraction → backend, frontend, database, auth, testing, etc.
• File ownership → maps files to components, prevents conflicts
• Dependency analysis → topological sort for ordering
• Wave generation → groups independent work for parallel execution

Example: "Build a dashboard with API and database"

• Wave 1: Database + API (parallel, no deps)
• Wave 2: Frontend (depends on API)

🛡️ Continuation & Context Monitoring

Stop hook: Prevents premature exit during modes. Detects incomplete tasks. Allows user stops.

PostToolUse hook: Tracks tokens. Warning at 75%. Critical at 90%. 30s cooldown. Max 5 warnings.

📟 HUD System

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

📊 Rate Limits 5h + weekly bars

🔌 CLI Status Codex + Gemini

📡 Active Jobs Running + done

💰 Cost Session estimate

📐 Context Usage bar

Configure with /claude-forge:hud.

📐 Architecture

MCP Servers

⬛ forge-codex codex_exec · codex_status · codex_cancel · codex_list Spawns codex exec --yolo via stdin GPT-5.3 · 128K context · Backend specialist

🟩 forge-gemini gemini_exec · gemini_status · gemini_cancel · gemini_list Spawns gemini -y via stdin Gemini 3 Pro · 1M context · Frontend specialist

Security: Path-validated context files • System directory blocklist • Basename-only CLI resolution • Anti-loop sandwich pattern • 10MB output cap • Conditional tool registration

Hook System

flowchart LR
    A["SessionStart"] --> B["CLI Detection\nInstruction Injection"]
    C["UserPromptSubmit"] --> D["Keyword Router\n95 Patterns"]
    E["PreToolUse"] --> F["Per-Tool Hints\nAgent Tracking"]
    G["PostToolUse"] --> H["Context Monitor\n75%/90% Warnings"]
    I["Stop"] --> J["Continuation\nEnforcement"]

    style A fill:#1a7f37,stroke:#3fb950,color:#fff
    style C fill:#1f6feb,stroke:#58a6ff,color:#fff
    style E fill:#9a6700,stroke:#d29922,color:#fff
    style G fill:#8250df,stroke:#bc8cff,color:#fff
    style I fill:#da3633,stroke:#ff7b72,color:#fff
    style B fill:#0d1117,stroke:#3fb950,color:#8b949e
    style D fill:#0d1117,stroke:#58a6ff,color:#8b949e
    style F fill:#0d1117,stroke:#d29922,color:#8b949e
    style H fill:#0d1117,stroke:#bc8cff,color:#8b949e
    style J fill:#0d1117,stroke:#ff7b72,color:#8b949e

📁 File Structure

claude-forge/
├── .claude-plugin/
│   ├── plugin.json              Plugin manifest (skills, MCP, hooks, agents)
│   └── marketplace.json         Marketplace registration
├── .mcp.json                    MCP server declarations
├── agents/                      30 agent definitions
├── hooks/hooks.json             5 lifecycle hooks
├── hud/
│   ├── forge-hud.mjs            HUD renderer
│   └── usage-api.mjs            Anthropic Usage API + OAuth
├── scripts/
│   ├── keyword-router.mjs       UserPromptSubmit (95 patterns)
│   ├── session-init.mjs         SessionStart (CLI detection)
│   ├── context-monitor.mjs      PostToolUse (context tracking)
│   ├── pre-tool-enforcer.mjs    PreToolUse (per-tool hints)
│   ├── continuation.mjs         Stop (exit prevention)
│   └── lib/                     Routing, keywords, complexity, decomposition
├── servers/
│   ├── codex-server.mjs         Codex CLI MCP server
│   └── gemini-server.mjs        Gemini CLI MCP server
├── skills/                      42 skill definitions
└── templates/CLAUDE.md          Injected delegation instructions

💡 Examples

🤖 Autonomous Build autopilot: Build user auth with JWT, password hashing, rate limiting, and email verification 5 phases: expand → plan → execute → QA → validate	⚡ Parallel Refactor ultrawork: Migrate the entire codebase from CommonJS to ESM Decompose → file ownership → parallel agents → verify
🔍 Cross-Review forge review the authentication PR Codex reviews logic/security, Gemini reviews design/UX. Unified report.	💰 Budget Mode ecomode: Add form validation to the signup page Haiku classifies, Sonnet implements. Same quality, ~3x cheaper.

🆚 Comparison

	Claude Code	+ claude-forge
🧠 Models	Claude only	Claude + GPT + Gemini
⚡ Parallelism	Sequential	Up to 5 agents
📐 Context	200K	200K + 128K + 1M
🤖 Autonomous	Manual	Autopilot, Ralph, Ultrawork
🔍 Review	Single perspective	Multi-model cross-review
🎯 Routing	Manual	Automatic classification
💰 Cost	One tier	Complexity-based routing

vs oh-my-claudecode (OMC)

	OMC	claude-forge
Focus	Claude-native orchestration	Multi-CLI delegation
External CLIs	Optional MCP	Core feature
Skills	37	42
Build	TypeScript + esbuild	Pure ESM, no build
LSP/AST	Yes (via MCP)	No
State	SQLite	File-based JSON

Use forge when multi-CLI delegation is primary. Use OMC for Claude-native orchestration with LSP/AST.

🔧 Troubleshooting

❌ Codex CLI not found

npm install -g @openai/codex && export OPENAI_API_KEY=sk-...
/claude-forge:enable-codex

❌ Gemini CLI not found

npm install -g @google/gemini-cli && gemini auth
/claude-forge:enable-gemini

❌ Skills not appearing

Run /claude-forge:doctor — 7 diagnostic checks with auto-fix.

❌ Cancel a stuck mode

/claude-forge:cancel --force

🤝 Contributing

Pure ESM JavaScript, no build step. Contributions welcome.

Adding a Skill

• Create skills/your-skill/SKILL.md with YAML frontmatter
• Write <Purpose>, <Use_When>, <Steps> sections
• Add trigger patterns to scripts/keyword-router.mjs
• Update templates/CLAUDE.md

📄 License

GPL-3.0 — Free software. Share alike.

claude-forge — Because one AI model is never enough.

GitHub   •   Issues   •   Discussions