claude-forge

🎉 v3.0.2 released (May 2026) — docs-only patch on top of v3.0.1: LLM-readable install paths (root INSTALL.md + above-the-fold one-liner) and multi-channel distribution. The v3.0.1 baseline brought Anthropic 2026 standard alignment (Hooks 21+ events · Subagent frontmatter v2 · Skills/Commands hybrid policy) plus a 4-server MCP minimum (playwright · context7 · jina-reader · chrome-devtools@0.23.0). See MIGRATION.md / MIGRATION.ko.md, Release v3.0.2, Release v3.0.1.

🚀 Install in one line (full install, recommended):

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

Or, inside an existing Claude Code session: /plugin marketplace add sangrokjung/claude-forge then /plugin install claude-forge (lightweight, plugin-only). Full details: INSTALL.md.

What is Claude Forge?

Claude Forge is an open-source development environment for Claude Code that provides 11 specialized agents, 33 slash commands, 24 skill workflows, 15 automation hooks (plus 9 opt-in examples covering 21 lifecycle events), and 9 rule files. Often described as "oh-my-zsh for Claude Code", it transforms Claude Code from a basic CLI into a full-featured development environment. One install gives you agents, commands, skills, hooks, and rules — all pre-wired and ready to go.

Think of it as oh-my-zsh for Claude Code: the same way oh-my-zsh enhances your terminal, Claude Forge supercharges your AI coding assistant.

⚡ Quick Start

Option 1 — Claude Code Plugin (partial coverage, v3.0.1+)

Inside Claude Code, register the marketplace once, then install the plugin:

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

Update later via /plugin update claude-forge (or from the /plugin UI).

⚠️ Partial coverage — please read before choosing. The Claude Code plugin loader currently recognizes commands/ and (most of) skills/ but does not auto-wire agents/, hooks/, rules/, statusLine, settings.json env blocks, or the entries inside mcp-servers.json. That is a loader limitation, not a claude-forge one — see docs/PLUGIN-VS-INSTALL-SH.md for the full matrix. If you want every resource (agents, hooks, rules, MCP, statusLine) wired up, use Option 2 below.

Option 2 — Classic install.sh (full symlink install, recommended)

# 1. Clone (submodules optional — only needed for the CC CHIPS status bar)
git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge

# 2. Install (creates symlinks under ~/.claude)
./install.sh

# 3. Launch Claude Code
claude

install.sh symlinks every resource into ~/.claude/, so git pull updates instantly, and it is the only install path that delivers agents, hooks, rules, the 4 MCP servers, and the status bar in one shot. Clone without --recurse-submodules still works: the CC CHIPS submodule is optional and the installer skips it cleanly if the directory is empty (a one-line hint is printed).

Which option should I pick?

| Resource | Option 1 (/plugin install) | Option 2 (./install.sh) | |----------|:----------------------------:|:-------------------------:| | Commands (33) | ✅ | ✅ | | Skills (24) | ⚠️ partial¹ | ✅ | | Agents (11) | ❌ | ✅ | | Hooks (15 + 9 examples)| ❌² | ✅ | | Rules (9) | ❌ | ✅ | | MCP servers (4) | ❌³ | ✅ | | statusLine (CC CHIPS) | ❌ | ✅ (opt-in submodule) | | settings.json env | ❌ | ✅ |

¹ Plugin-loaded skills are supported, but QJC skill features that reach into ~/.claude/rules/ or ~/.claude/agents/ assume the symlink layout. ² See hooks/hooks.json: Claude Code does not load a separate hooks.json; all hook settings must live in settings.json, which Option 1 does not merge. ³ plugin.json does not currently surface mcpServers in a way the loader acts on. MCP servers come from .mcp.json / mcp-servers.json, which only Option 2 wires up.

Recommendation: Use Option 2 unless you only need Commands + a subset of Skills.

If you find Claude Forge useful, please consider giving it a star -- it helps others discover this project.

🎉 What's New in v3.0

| Change | Description | |:-------|:------------| | Hooks 21 Events | Lifecycle hooks expanded from 5 to 21 events. Opt-in samples live at hooks/examples/ with the full catalog in hooks/README.md. | | Subagent Frontmatter v2 | 10 optional fields: isolation, background, memory, maxTurns, skills, mcpServers, effort, hooks, permissionMode, disallowedTools. Schema: reference/agent-schema.json. Details: docs/AGENT-FRONTMATTER-V2.md. | | Skills/Commands Hybrid Policy | Clear boundary documented at docs/SKILLS-VS-COMMANDS.md. 8 directory-form commands are being migrated to skills/ with symlink compatibility preserved. | | MCP Minimal (4 servers, v3.0.1) | Default set: playwright · context7 · jina-reader · chrome-devtools-mcp@0.23.0 (Google ChromeDevTools org, Apache-2.0 — promoted in v3.0.1 for Lighthouse / Core Web Vitals audits). The legacy full set lives in mcp-servers.optional.json. Recipes: docs/MCP-MIGRATION.md. Decision rationale: docs/adr/ADR-001-mcp-default-set.md. | | CLAUDE.md Template + @import | New setup/CLAUDE.md.template and docs/CLAUDE-MD-GUIDE.md with a 200-line principle and @import pattern for modular project instructions. | | settings.json 2026 Fields | New fields: tui (flicker-free rendering), disableSkillShellExecution (sandbox), enabledMcpjsonServers (explicit allowlist). | | Upgrade in One Command | ./install.sh --upgrade safely migrates existing v2.1 installs with backup and diff preview. |

🔧 What's New in v3.0.1 (patch)

| Change | Description | |:-------|:------------| | Plugin Manifest shipped (partial) | /plugin marketplace add sangrokjung/claude-forge + /plugin install claude-forge now work for Commands + Skills. .claude-plugin/plugin.json + .claude-plugin/marketplace.json both pinned to 3.0.2; CI enforces version drift via the new marketplace-schema job. Agents / Hooks / Rules / MCP / statusLine still require ./install.sh — see docs/PLUGIN-VS-INSTALL-SH.md. | | Chrome DevTools promoted | Lighthouse / Core Web Vitals / memory snapshots now arrive with the default 4-server MCP set. Pinned at chrome-devtools-mcp@0.23.0 (supply-chain hardening). | | hooks/_lib/timing.sh | New wrapper records SessionEnd hook timing into ~/.claude/logs/hook-timing.jsonl (mode 600) so the real parallelism of async: true hooks can be audited post-hoc. ~35 ms overhead. | | CI trigger expanded | .github/workflows/validate.yml now runs on every PR and on main/feat/**/fix/**/chore/**/docs/**/ci/** pushes (previously main only). 6 jobs total. | | Tier 0 spec corrections | Hook types aligned to command/http/prompt/agent (were llm-prompt/mcp-tool). timeout unit corrected to seconds (was ms). Auto Memory path ~/.claude/projects/<project>/memory/ (was <hash>). | | New governance docs | docs/adr/ADR-001-mcp-default-set.md (MCP default decision, MADR) · docs/SETTINGS-COMPATIBILITY.md (UNVERIFIED field tracking) · [docs/MARKETPLACE-SUBMISSION.md](d