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.
rca-debugger	Escalation from systematic-debugger for multi-system failures — 5-why + fishbone analysis when bisection alone is inconclusive.
escalation-fixer	Last resort when build-error-resolver can't close a build error — allowed architectural-level changes, reads the escalation log to avoid repeating failed approaches.

Core Workflow

Command	What it does
/plan	AI creates an implementation plan. Waits for your confirmation before coding.
/tdd	Write tests first, then code. One unit of work at a time.
/code-review	Security + quality check on the code you just wrote.
/handoff-verify	Auto-verify build/test/lint all at once.
/commit-push-pr	Commit, push, create PR, and optionally merge — all in one.
/quick-commit	Fast commit for simple, well-tested changes.
/verify-loop	Auto-retry build/lint/test up to 3x with auto-fix.
/auto	One-button automation: plan to PR without stopping.
/guide	Interactive 3-minute tour for first-time users.
/loop-forge	Turn a repetitive task into a reusable, self-guarding slash command.
/workflow-classify	Size a task S/M/L/XL and route documentation depth + verification rigor accordingly.

Exploration & Analysis

Command	What it does
/explore	Navigate and analyze codebase structure.
/build-fix	Incrementally fix TypeScript and build errors.
/next-task	Recommend next task based on project state.
/suggest-automation	Analyze repetitive patterns and suggest automation.
/agent-router	Route a request to the specialist agent best suited for the task.

Security

Command	What it does
/security-review	CWE Top 25 + STRIDE threat modeling.

Testing & Evaluation

Command	What it does
/e2e	Generate and run Playwright end-to-end tests.
/test-coverage	Analyze coverage gaps and generate missing tests.
/eval	Eval-driven development workflow management.

Documentation & Sync

Command	What it does
/update-codemaps	Analyze codebase and update architecture docs.
/update-docs	Sync documentation from source-of-truth.
/sync-docs	Sync prompt_plan.md, spec.md, CLAUDE.md + rules.
/sync	Pull latest changes and sync all project docs. Use after any workflow or at session start.
/pull	Quick git pull origin main.
/forge-update	Update Claude Forge itself to the latest version from the remote.
/show-setup	Show the current install status and project info.

Project Management

Command	What it does
/init-project	Scaffold new project with standard structure.
/orchestrate	Agent Teams parallel orchestration.
/checkpoint	Save/restore work state.
/learn	Record lessons learned + suggest automation.
/web-checklist	Post-merge web testing checklist.

Refactoring & Debugging

Command	What it does
/refactor-clean	Identify and remove dead code with test verification.

Git Worktree

Command	What it does
/worktree-start	Create git worktree for parallel development.
/worktree-cleanup	Clean up worktrees after PR completion.

The 8 commands that moved to skills/ in v3.0 (debugging-strategies, dependency-upgrade, evaluating-code-models, evaluating-llms-harness, extract-errors, security-compliance, stride-analysis-patterns, summarize) are listed once, under Skills below — see MIGRATION.md Step 5. install.sh still creates compatibility symlinks under commands/ for them.

Skill	What it does
blind-spot-pass	Before starting work in an unfamiliar domain, surface what you don't know you don't know (unknown unknowns) and teach just enough to prompt well. Shift-left discovery.
build-system	Auto-detect and run project build systems.
cache-components	Next.js Cache Components and Partial Prerendering (PPR) guidance.
cc-dev-agent	Claude Code development workflow optimization (context engineering, sub-agents, TDD).
continuous-learning-v2	Instinct-based learning: observe sessions via hooks, create atomic instincts with confidence scoring.
debugging-strategies	Systematic debugging techniques and profiling.
dependency-upgrade	Major dependency upgrades with compatibility analysis.
eval-harness	Formal evaluation framework for eval-driven development (EDD).
evaluating-code-models	Benchmark code generation models (HumanEval, MBPP).
evaluating-llms-harness	Benchmark LLMs across 60+ academic benchmarks.
extract-errors	Extract and catalog error messages.
frontend-code-review	Frontend file review (.tsx, .ts, .js) with checklist rules.
harness-diet	Measure and shrink always-loaded context (CLAUDE.md + rules) back under budget: migrate narrative to references, path-scope or skill-ify rules, verify zero governance loss with deterministic preservation checks.
humanize-korean	Strip translation-ese and AI idioms from Korean prose without changing facts, numbers, or register.
korean-character-count	Count Korean characters/syllables for length-constrained copy (titles, SMS, ad copy).
korean-spell-check	Check Korean spelling and spacing. Sends the text to the third-party service nara-speller.co.kr, so keep client names and personal data out of it.
loop-forge	Turn a one-line repetitive task into a reusable, self-guarding slash command (5 loop shapes + auto verifier & hardstop).
manage-skills	Analyze session changes, detect missing verification skills, create/update skills.
prompts-chat	Skill/prompt exploration, search, and improvement.
relay	Session handoff across /compact: writes a /compact one-liner plus a "baton" file with the next task, key files, and facts pulled verbatim from git/plan/session-summary state.
review-loop	The adversarial verification loop procedure: dispatch adversarial-reviewer, act on REQUEST_CHANGES, stop only on APPROVE against the current revision.
security-compliance	SOC2, ISO27001, GDPR, HIPAA compliance checks.
security-pipeline	CWE Top 25 + STRIDE automated security verification pipeline.
session-wrap	End-of-session cleanup: 4 parallel subagents detect docs, patterns, learnings, follow-ups.
skill-factory	Convert reusable session patterns into Claude Code skills automatically.
strategic-compact	Suggest manual context compaction at logical intervals to preserve context.
stride-analysis-patterns	Systematic STRIDE methodology for threat identification.
summarize	Summarize URLs, podcasts, transcripts, local files.
systematic-debugging	6-phase structured debugging procedure — reproduce, isolate, hypothesize, test, fix, verify.
team-orchestrator	Agent Teams engine: team composition, task distribution, dependency management.
using-superpowers	Discover and invoke installed skills before responding to any request.
verification-engine	Integrated verification engine: fresh-context subagent verification loop.
verify-implementation	Run all project verify skills and generate unified pattern verification report.

Security Hooks — block dangerous actions automatically

Hook	When it runs	What it blocks
output-secret-filter.sh	After every tool use	Leaked API keys, tokens, passwords in output
remote-command-guard.sh	Before Bash commands	Unsafe remote commands (curl pipe, wget pipe)
db-guard.sh	Before database commands	Destructive SQL (DROP, TRUNCATE, DELETE without WHERE)
security-auto-trigger.sh	After file edits	Vulnerabilities in code changes
rate-limiter.sh	Before MCP tool use	MCP server abuse / excessive calls
mcp-usage-tracker.sh	Before MCP tool use	Tracks MCP usage for monitoring

Reliability Hooks — v4.0, unattended-session safety net

Hook	When it runs	What it does
api-error-auto-resume.sh	Session ends on a retryable API error (StopFailure)	Classifies the failure, then schedules an unattended resume under fork-bomb-style caps. Full contract: rules/api-error-recovery.md
loop-detection.sh	After 5/10+ edits to the same file in one session	Nudges a rethink instead of letting the session spin — see docs/RELIABILITY.md
auto-verify-fix.sh	After editing a .ts/.tsx/.js/.jsx/.py file	Lightweight type/syntax check, surfaces fixable errors immediately
pre-compact-snapshot.sh	Before context compaction (PreCompact)	Snapshots the pointer to the most recent relay skill baton
post-compact-restore.sh	Right after /compact (SessionStart, matcher compact)	Restores that pointer into the fresh session's context, exactly once
emdash-slop-guard.sh	After editing a .md file whose content is substantially Korean	Flags em-dash AI-tell interjections — see rules/korean-writing-quality.md

Utility Hooks — helpful nudges in the background

Hook	When it runs	What it does
code-quality-reminder.sh	After file edits	Reminds about immutability, small files, error handling
context-sync-suggest.sh	Session start	Suggests syncing docs at session start
forge-update-check.sh	Session start	Tells you when a newer claude-forge release is available
session-wrap-suggest.sh	Before session end	Suggests session wrap-up before ending
session-time-report.sh	Session ends, replayed at your next session start	Reports end time, how long it ran, and prompt/tool/file-change counts — see End-of-session report
work-tracker-prompt.sh	When you submit a prompt	Tracks work for analytics
work-tracker-tool.sh	After tool use	Tracks tool usage for analytics
work-tracker-stop.sh	On stop	Finalizes work tracking data
task-completed.sh	When subagent finishes	Notifies on subagent task completion
expensive-mcp-warning.sh	Before costly operations	Warns about expensive MCP calls

An opt-in pre-commit secret guard (scripts/install-precommit.sh) also ships as of v4.0 — it protects git commits in any repo you point it at, separately from the hooks above. See docs/RELIABILITY.md.

End-of-session report

session-time-report.sh measures a session as it closes and hands you the summary the next time you open one:

[Claude Forge] Previous session ended 21:34 KST
2h 17m elapsed · 18 prompts · 143 tool calls · 9 files changed
Log: ~/.claude/work-log/session-time-<session_id>.json

Why it is wired to two events. SessionEnd is where the numbers are, but it cannot talk to you: Claude Code forwards a SessionEnd hook's output only when that hook failed, so a successful report is thrown away. SessionStart is a channel that does reach you. So the same script records on the way out and reports on the way in, exactly once per session.

It reads only the session transcript, so there is no network call and no extra dependency beyond python3.

It also reads Codex. Codex 0.150 has the same hook events and writes its own rollout log; the hook works out which dialect a transcript is in and counts either one, naming the agent in the line it prints. install.sh only wires Claude Code, so the two Codex entries are yours to add: hooks/README.md has them.

Elapsed time is resume-aware. A transcript you reopened days later spans hundreds of hours of wall clock, which is not what you worked. The hook splits the timeline wherever there is a long idle gap and reports the latest stretch; if the session was resumed, it appends (resumed 3x, 9h 40m total).

Environment variable	Default	Effect
FORGE_SESSION_TIME_REPORT	1	Set to 0 to turn the hook off
FORGE_SESSION_GAP_MIN	60	Idle minutes that start a new stretch
FORGE_SESSION_MAX_MB	128	Transcript megabytes to scan, up to 512; larger files are read from the tail
FORGE_SESSION_MAX_SEC	4	Wall-clock budget for the scan. Past it the report is dropped rather than reported half-read
FORGE_SESSION_REPORT_LANG	auto	en or ko; auto-detects from LANG / LC_ALL

Every run also appends to ~/.claude/work-log/session-times.jsonl (mode 600, rotated at 1 MB), so you can chart your own sessions later. Reports queue in ~/.claude/work-log/.session-time-pending.jsonl until a session drains them, so ending several sessions before starting a new one does not lose any of them. Log files are created 0600 and the hook refuses to follow a symlink planted at one of those paths.

Opt-in Examples (9 extra, v3.0+)

9 additional .example files live in hooks/examples/, one per event: PostCompact, PostToolUseFailure, PreCompact, StopFailure, SubagentStart, SubagentStop, TaskCreated, WorktreeCreate, WorktreeRemove. Full 21-event coverage; 27-event catalog: hooks/README.md. To activate: rename *.example → *.sh and register in settings.json.

---

🔄 How to Use It

The main development pipeline

Claude Forge's commands are designed to chain together. Here is the recommended flow for building any new feature:

/plan → /tdd → /code-review → /handoff-verify → /commit-push-pr

Step	What Claude does	Why
/plan	Writes an implementation plan and waits for your go-ahead	No code is written until you approve the approach
/tdd	Writes the tests first, then writes the code to pass them	Catches mistakes before they become bugs
/code-review	Checks the finished code for security holes and quality issues	A second pair of eyes, automatically
/handoff-verify	Runs build, tests, and lint in a fresh session to confirm everything passes	Catches "works on my machine" problems
/commit-push-pr	Commits the code, pushes to GitHub, creates a pull request, and optionally merges it	One command to ship

Other common workflows

Fixing a bug:

/explore → /tdd → /verify-loop → /quick-commit → /sync

Security audit:

/security-review → /stride-analysis-patterns → /security-compliance

Parallel team work (multiple agents at once):

/orchestrate → Agent Teams (working in parallel) → /commit-push-pr

Not sure where to start?

After installing, type /guide for an interactive 3-minute tour. Or just type:

/auto login page

Claude Forge will handle the entire plan-to-PR pipeline for you automatically.

Prefer to read first? docs/FIRST-STEPS.md walks through your first session step by step, and docs/WORKFLOW-RECIPES.md collects the command sequences for common jobs.

---

🏗 Architecture

The installer creates symbolic links (shortcuts) from the claude-forge folder to ~/.claude/ — the folder Claude Code reads. This means git pull in the repo updates everything instantly, with no reinstall needed.

graph LR
    REPO["claude-forge repo<br>(git pull to update)"]
    INSTALL["./install.sh<br>(one-time setup)"]
    HOME["~/.claude/<br>(Claude reads this)"]
    CLAUDE["Claude Code"]

    REPO --> INSTALL
    INSTALL -->|"creates symlinks"| HOME
    HOME --> CLAUDE

Skills vs Commands: skills/ are knowledge and procedures Claude discovers and follows automatically. commands/ are explicit actions you trigger by typing /name. See docs/SKILLS-VS-COMMANDS.md.

claude-forge/
  ├── agents/                    Agent definitions (16 .md files, frontmatter v2)
  ├── cc-chips/                  Status bar submodule
  ├── cc-chips-custom/           Custom status bar overlay
  ├── commands/                  Slash commands (35 .md, 8 dirs moved to skills/)
  ├── docs/                      Screenshots, diagrams, policy docs (v3.0+ guides, incl. RELIABILITY.md / VERIFICATION-LOOP.md)
  ├── hooks/                     Event-driven shell scripts (22)
  │   └── examples/              Opt-in .example samples for 21 lifecycle events (9)
  ├── knowledge/                 Knowledge base entries
  ├── libs/                      Shared shell libraries hooks source (hook-guard.sh)
  ├── reference/                 Reference docs (+ agent-schema.json, ai-tell-taxonomy.md)
  ├── rules/                     Auto-loaded rule files (14)
  ├── scripts/                   Utility scripts (incl. install-precommit.sh, api-error-resume-runner.sh)
  ├── setup/                     Installation guides + CLAUDE.md template
  ├── skills/                    Multi-step skill workflows (33, hybrid policy)
  ├── install.sh                 macOS/Linux installer (--upgrade supported)
  ├── install.ps1                Windows installer (--upgrade supported)
  ├── mcp-servers.json           MCP server defaults (4 minimal)
  ├── mcp-servers.optional.json  Optional MCP servers (memory/exa/github/fetch/time/...)
  ├── .claude-plugin/plugin.json Plugin manifest (4.3.0)
  ├── .claude-plugin/marketplace.json  Marketplace entry (4.3.0)
  ├── settings.json              Claude Code settings (2026 fields)
  ├── MIGRATION.md               v2.1 → v4.0 migration guide (EN)
  ├── MIGRATION.ko.md            v2.1 → v4.0 migration guide (KO)
  ├── CONTRIBUTING.md            Contribution guide
  ├── SECURITY.md                Security policy
  └── LICENSE                    MIT License

---

🔧 What's New in v4.0

Change	Description
Adversarial verification loop	adversarial-reviewer + skeptical-auditor agents, review-loop skill, rules/adversarial-review.md. Maker≠checker: a fresh, independent reviewer that did not write the change reproduces the claim rather than reading it, and returns APPROVE / REQUEST_CHANGES / UNVERIFIED. Worked example from this release's own PRs: docs/VERIFICATION-LOOP.md.
Reliability pack	Unattended API-error auto-resume (StopFailure), session relay across /compact, doom-loop + edit-time verify hooks, an opt-in pre-commit secret guard, and the shared libs/hook-guard.sh they build on. Full wiring guide: docs/RELIABILITY.md.
Debugging escalation chain	systematic-debugger → rca-debugger → escalation-fixer. Each step only fires when the one before it couldn't close the case.
Task-grade routing	/workflow-classify sizes a task S/M/L/XL and routes documentation depth and verification rigor accordingly (rules/task-grade-routing.md).
Korean prose quality guardrails	Translation-ese and AI-idiom avoidance at generation time, not just a cleanup pass — rules/korean-writing-quality.md, reference/ai-tell-taxonomy.md, emdash-slop-guard.sh, plus humanize-korean / korean-character-count / korean-spell-check skills.

Inventory: 11 → 16 agents, 34 → 35 commands, 26 → 32 skills, 15 → 21 hooks, 10 → 14 rules. See MIGRATION.md for the full v3 → v4 upgrade guide.

🔧 What's New in v3.0 (historical)

v3.1.0 (feature, June 2026)

• loop-forge skill + command — turn a one-line repetitive task into a reusable, self-guarding slash command (5 loop shapes + auto verifier & hardstop). Skills 24 → 25, commands 33 → 34.
• Beginner-friendly README — full rewrite for non-developers (plain-language analogies, terms explained in parentheses) + 3 diagrams (what's inside / install in 3 steps / development workflow), in English & Korean.

v3.0.2 (docs patch, May 2026)

LLM-readable install paths (root INSTALL.md + above-the-fold one-liner) and multi-channel distribution. See Release v3.0.2.

v3.0.1 (patch)

Change	Description
Plugin Manifest shipped	/plugin marketplace add sangrokjung/claude-forge + /plugin install claude-forge now work for Commands + Skills.
Chrome DevTools promoted	Lighthouse / Core Web Vitals / memory snapshots now in the default 4-server set. Pinned at [email protected].
hooks/_lib/timing.sh	Records SessionEnd hook timing into ~/.claude/logs/hook-timing.jsonl.
CI expanded	Runs on every PR and on main/feat/**/fix/**/chore/**/docs/**/ci/** pushes. 6 jobs total.
Tier 0 spec corrections	Hook types, timeout units, Auto Memory path all corrected.
New governance docs	ADR-001, SETTINGS-COMPATIBILITY, MARKETPLACE-SUBMISSION.

v3.0 (major)

Change	Description
Hooks 21 Events	Lifecycle hooks expanded from 5 to 21 events. Opt-in samples in hooks/examples/.
Subagent Frontmatter v2	10 optional fields: isolation, background, memory, maxTurns, skills, mcpServers, effort, hooks, permissionMode, disallowedTools. Schema: reference/agent-schema.json.
Skills/Commands Hybrid Policy	Clear boundary documented at docs/SKILLS-VS-COMMANDS.md.
MCP Minimal (4 servers)	Default set: playwright · context7 · jina-reader · [email protected]. Legacy full set in mcp-servers.optional.json.
CLAUDE.md Template	New setup/CLAUDE.md.template with @import pattern.
Upgrade in One Command	./install.sh --upgrade safely migrates v2.1 installs with backup and diff preview.

Breaking Changes in v3.0

• MCP defaults cut — memory, exa, github, and fetch removed from mcp-servers.json. Restore from mcp-servers.optional.json if needed.
• 8 commands moved to skills/ — Symlink compatibility maintained until 2027-04-01. Affected: debugging-strategies, dependency-upgrade, evaluating-code-models, evaluating-llms-harness, extract-errors, security-compliance, stride-analysis-patterns, summarize.
• settings.json allowlist — Removed mcp__memory, mcp__exa, mcp__github, mcp__fetch. Added mcp__playwright.

---

🛠 MCP Servers (External Tool Connections)

Server	What it does	Required setup
playwright	Controls a real browser for end-to-end tests	None — auto-installed
context7	Fetches live library documentation while coding	None — auto-installed
jina-reader	Reads web pages and converts them to clean text	None — auto-installed
chrome-devtools	Runs Lighthouse audits and Core Web Vitals checks	None — auto-installed

Additional servers (memory, exa search, GitHub, fetch) are available opt-in via mcp-servers.optional.json. Full recipes: docs/MCP-MIGRATION.md.

---

⚙️ Customization

Override any setting without modifying tracked files:

cp setup/settings.local.template.json ~/.claude/settings.local.json
# Edit ~/.claude/settings.local.json with your preferences

settings.local.json merges on top of settings.json automatically — your changes survive git pull.

---

🆚 Claude Forge vs. Starting From Scratch

Feature	Claude Forge	Basic .claude/ setup	Individual plugins
Specialist agents	16 ready	Manual setup	Varies
Slash commands	35 ready	None	Per-plugin
Skill workflows	33 ready	None	Per-plugin
Safety hooks	22 + 9 examples	None by default	Per-plugin
External tool connections	4 default (8+ optional)	None	Per-plugin
Setup time	~5 minutes	Hours	Per-plugin install
Updates	git pull	Manual per-file	Per-plugin update
End-to-end pipeline	Plan → Test → Review → Ship	Disconnected tools	Not integrated

---

❓ FAQ

Claude Forge is built for developers working with Claude Code, so some familiarity with the terminal is needed. That said, you do not need to understand all the internals — most workflows start with a simple one-word command like /plan or /auto, and Claude Forge handles the rest.

If you are new, start with /guide after installing. It gives you an interactive 3-minute tour.

Claude Code is Anthropic's official AI coding assistant that runs in your terminal. It reads your codebase, writes code, runs tests, and more — all through a conversation. Claude Forge is the add-on kit that gives it specialist helpers, shortcuts, and safety checks.

Most Claude Code plugins solve one problem at a time. Claude Forge is a complete development environment — 16 agents, 35 commands, 33 skills, 22 hooks, and 14 rules that work together as a cohesive system. Instead of assembling individual plugins, you get a pre-wired pipeline: /plan feeds into /tdd, which feeds into /code-review, which feeds into /handoff-verify, which feeds into /commit-push-pr — and, new in v4.0, an adversarial verification loop that a fresh reviewer must APPROVE before any behavioral change is considered done. The 6-layer security hook system also runs automatically without extra configuration.

Yes. Claude Forge installs via symlinks to ~/.claude/ and works alongside official Claude Code plugins. Your existing settings.local.json overrides are preserved, and you can add or remove individual components without affecting the rest of the system.

Run git pull in the claude-forge directory. Because the installer uses symlinks (on macOS/Linux), updates take effect immediately — no re-install needed. On Windows, re-run install.ps1 after pulling to copy the updated files.

Yes. Run install.ps1 in PowerShell as Administrator. Windows uses file copies instead of symlinks, so re-run install.ps1 after each git pull to apply updates. Agents, commands, and skills work the same on Windows, macOS, and Linux. The v4.0.0 reliability hooks (auto-resume, session relay, doom-loop detection, and the rest of S1-S5) were built and verified on macOS only — Linux/WSL was addressed at the source level but not exercised, and two of the auto-resume paths were never fired on any platform in this release. See the platform matrix in docs/RELIABILITY.md for the exact breakdown.

/sync pulls the latest changes from your remote repository and then synchronizes all project documentation — prompt_plan.md, spec.md, CLAUDE.md, and rule files. Run it after completing any workflow (feature, bug fix, refactor) or at the start of a new session to make sure Claude has the latest context about your project.

Claude Forge uses a 4-layer memory system:

1. Project docs (CLAUDE.md, prompt_plan.md, spec.md) — Project-level instructions and plans that persist in the repository. /sync keeps these up to date.
2. Rule files (rules/) — Coding style, security, and workflow conventions loaded automatically each session.
3. MCP memory server — A persistent knowledge graph that stores entities and relations across sessions (opt-in).
4. Agent memory (~/.claude/agent-memory/) — Core agents record learnings after each task, improving their recommendations over time.

Running /sync at session start ensures layers 1 and 2 are current.

---

🤝 Contributing

See CONTRIBUTING.md for guidelines on adding agents, commands, skills, and hooks.

---

Use Claude Forge? Show it!

[![Built with Claude Forge](https://img.shields.io/badge/Built_with-Claude_Forge-orange?style=flat-square)](https://github.com/sangrokjung/claude-forge)

Add this badge to your project's README to let others know you use Claude Forge.

---

⭐ Star History

---

Contributors

---

📄 License

MIT — use it, fork it, build on it.

If Claude Forge improved your workflow, a star helps others find it too.

---