claude-forge

v4.3.0 (September 2026, latest) — session-time-report now reads Codex too. Same hook, same report; it detects whether a transcript is a Claude Code transcript or a Codex rollout log and counts either. Wiring for Codex is two entries you add to ~/.codex/hooks.json (how).

v4.2.0 (September 2026) — Adds session-time-report (22nd hook): measures each session as it closes and tells you at your next start what time it ended, how long it actually ran, and how much you got through. Resume-aware, so a session you picked back up days later reports that sitting rather than a bogus 400-hour total.

v4.1.0 (August 2026) — Adds harness-diet (33rd skill): measure your always-loaded context (CLAUDE.md + rules) and shrink it back under budget without losing governance.

v4.0.0 (August 2026) — Introduces the adversarial verification loop: every behavioral change is checked by a second, independent agent that did not write the code and never sees the first agent's reasoning — maker≠checker until it issues APPROVE. Building v4.0 itself, the loop caught three real defects in the maintainer's own PRs (#58, #61); worked example: docs/VERIFICATION-LOOP.md. Also ships a reliability pack (API-error auto-resume, session relay across /compact, doom-loop guard — docs/RELIABILITY.md), a debugging escalation chain, task-grade routing, and Korean prose quality guardrails. Details: What's New in v4.0 · MIGRATION.md.

If /plugin install claude-forge ever showed ✘ failed to load (Hook load failed: expected record, received undefined), that bug is fixed as of v4.0.0 — see #52, #57.

v3.1.0 (June 2026) — Adds loop-forge (turn a repetitive task into a reusable, self-guarding slash command) and a full beginner-friendly rewrite of this README with diagrams. Built on v3.0.2 (LLM-readable install) and v3.0.1 (Anthropic 2026 standard alignment: Hooks 21+ events, Subagent frontmatter v2, Skills/Commands hybrid policy, 4-server MCP minimum). See MIGRATION.md.

---

What is Claude Forge?

Plain English version: Claude Code is an AI coding assistant that lives in your terminal. Out of the box it is capable but bare — like a new employee who knows how to code but has no company procedures, no safety checklists, no templates, and no specialist colleagues to call on.

Claude Forge is the equipment pack for that assistant. One install gives it:

• 16 specialist "colleagues" (agents) it can delegate to — planner, security reviewer, TDD guide, adversarial reviewer, and more
• 35 one-word shortcuts (commands like /plan, /tdd, /code-review) that trigger full workflows
• 33 saved procedures (skills) it follows automatically
• 22 safety checks (hooks) that run silently in the background every time it touches your code — including an unattended API-error auto-resume, a doom-loop guard, and an end-of-session time report
• 14 rule files that define how it should behave
• 4 external tool connections (browser automation, live docs search, and more)

The oh-my-zsh analogy: oh-my-zsh is a free add-on that turns a plain terminal into a colorful, plugin-packed power tool — without changing what the terminal fundamentally does. Claude Forge does the same thing for Claude Code.

---

✨ Why bother?

Without Claude Forge	With Claude Forge
Claude Code writes code, but you have to remind it about tests, security, and docs every time	Automated pipeline: plan → test → review → verify → ship, all connected
No safety net — Claude can run dangerous commands or leak secrets by accident	6-layer hook system blocks risky actions before they happen
One AI doing everything alone	16 specialist agents working in parallel (planner, architect, security reviewer, adversarial reviewer…)
Hours assembling your own config	5-minute install, everything pre-wired
Updates require manual copy-paste	git pull — done

---

📥 Install in Minutes

Option A — Claude Code Plugin (quick start, partial features)

Open a Claude Code session and run two commands:

/plugin marketplace add sangrokjung/claude-forge
/plugin install claude-forge

This gets you commands and most skills right away. Agents, hooks, rules, and MCP connections need Option B.

Update later: /plugin update claude-forge

Option B — Full Install (recommended, everything included)

One line in your terminal:

curl -fsSL https://raw.githubusercontent.com/sangrokjung/claude-forge/main/install.sh | bash

Or if you prefer to clone first:

git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge
./install.sh        # fresh install
# or
./install.sh --upgrade   # safe migration from v2.1

Windows users: Run .\install.ps1 in PowerShell as Administrator.

Which option should I pick?

What you get	Option A (/plugin install)	Option B (./install.sh)
Commands (35 shortcuts)	✅	✅
Skills (33 saved procedures)	⚠️ partial	✅
Agents (16 specialists)	❌	✅
Hooks (22 safety checks)	❌	✅
Rules (14 behavior guidelines)	❌	✅
MCP connections (4 tools)	❌	✅

Recommendation: Use Option B unless you only need a taste of commands and skills.

If Claude Forge helps you, a star on GitHub helps others find it.

---

📦 What's Inside

Here is everything bundled in Claude Forge, explained in plain language:

What	Count	Plain English
Agents (specialist colleagues)	16	Each one is an AI focused on a single job — planner, architect, security checker, test guide, database expert, adversarial reviewer, and more. Claude calls the right one automatically.
Commands (shortcut buttons)	35	Type /plan and Claude creates a full implementation plan. Type /tdd and it writes tests first, then code. All 35 are pre-built shortcuts for common developer tasks.
Skills (saved procedures)	33	Step-by-step playbooks Claude follows automatically — like a recipe it has memorized. loop-forge turns any repetitive task into a reusable slash command in seconds; review-loop runs the maker≠checker verification cycle.
Hooks (silent safety checks)	22 built-in + 9 opt-in examples	These run before and after every action Claude takes. They block leaked passwords, dangerous database commands, and unsafe remote scripts — and, new in v4.0, they auto-resume a session after a retryable API error and nudge you when you're stuck editing the same file. Covers 21 lifecycle events.
Rules (behavior guidelines)	14	Written instructions Claude reads at the start of every session — coding style, security principles, git workflow conventions, when the verification loop is mandatory, and more.
MCP connections (external tools)	4	Browser automation (Playwright), live library docs (context7), web page reader (jina-reader), and Chrome DevTools for performance audits.

Deep Analysis Agents (use the most capable model)

Agent	What it does
planner	Creates detailed implementation plans for complex features. Waits for your sign-off before any code is written.
architect	Designs system structure, makes scalability decisions, reviews technical architecture.
code-reviewer	Checks code quality, security, and maintainability after you write it.
security-reviewer	Scans for OWASP Top 10 vulnerabilities, leaked secrets, injection risks.
tdd-guide	Enforces test-first development: RED (failing test) → GREEN (passing) → IMPROVE (refactor).
database-reviewer	Optimizes PostgreSQL/Supabase queries, reviews schema design.

Fast Execution Agents (use a quicker model)

Agent	What it does
build-error-resolver	Fixes TypeScript and build errors with minimal changes to surrounding code.
e2e-runner	Generates and runs Playwright end-to-end browser tests.
refactor-cleaner	Finds and removes dead code using knip, depcheck, ts-prune.
doc-updater	Keeps documentation and code maps in sync after changes.
verify-agent	Opens a fresh context to verify build, lint, and tests all pass — like a second pair of eyes.

Verification & Debugging Agents (v4.0)

Agent	What it does
adversarial-reviewer	Independent, read-only checker for the verification loop. Never wrote the change, never sees the maker's reasoning — tries to break the claim rather than confirm it. Returns APPROVE, REQUEST_CHANGES, or UNVERIFIED.
skeptical-auditor	Re-audits a pass another agent already claimed: re-runs each step that was reported green and compares the real exit codes against the claim. Runs after verification, not instead of it — an independent verdict on the change itself is adversarial-reviewer's job.
systematic-debugger	Reproduce → bisect → hypothesize → verify. Never guesses at a fix without a failing test that proves the hypothesis.