claude-forge

Turn Claude Code into a full development environment

What's New v3.0 • Quick Start • Workflows • What's Inside • Installation • Architecture • Customization • 한국어

🎉 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 · [email protected]). See MIGRATION.md / MIGRATION.ko.md, Release v3.0.2, Release v3.0.1.

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

copy

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?

¹ 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

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

🚨 Breaking Changes

• MCP defaults cut — memory, exa, github, and fetch were removed from mcp-servers.json. Restore any of them from mcp-servers.optional.json if you need them. Built-in replacements: Auto Memory, the gh CLI, WebSearch, and the jina-reader fallback cover most previous use cases.
• 8 commands moved to skills/ — Symlink compatibility is 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.

Why v3.0?

The 2026 Anthropic Claude Code standard evolved significantly (Skills/Commands integration, 21 hook events, expanded subagent frontmatter). v3.0 aligns fully with that standard, cuts default MCP dependencies from 6 down to 4 (v3.0 shipped a 3-server minimum; v3.0.1 promoted [email protected] into the default set) to lower the barrier for new users, and incorporates dotclaude operational experience (security allowlists, breakage-safe migration). Existing v2.1 users can migrate with a single line: ./install.sh --upgrade.

New here?

If you're new to development or Claude Code, start with these:

Or just type /auto login page and let Claude Forge handle the entire plan-to-PR pipeline for you.

🔄 Development Workflows

Real-world workflows that chain commands, agents, and skills together.

Feature Development

Build new features with a plan-first, test-first approach:

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

graph LR
    P["/plan<br><small>Design & risk analysis</small>"] --> T["/tdd<br><small>Tests first, then code</small>"]
    T --> CR["/code-review<br><small>Quality & security check</small>"]
    CR --> HV["/handoff-verify<br><small>Fresh-context validation</small>"]
    HV --> CPR["/commit-push-pr<br><small>Commit, push, PR & merge</small>"]
    CPR --> S["/sync<br><small>Sync project docs</small>"]

    style P fill:#533483,stroke:#fff,color:#fff
    style T fill:#0f3460,stroke:#fff,color:#fff
    style CR fill:#0f3460,stroke:#fff,color:#fff
    style HV fill:#e94560,stroke:#fff,color:#fff
    style CPR fill:#1a1a2e,stroke:#fff,color:#fff
    style S fill:#16213e,stroke:#fff,color:#fff

Bug Fix

Fast turnaround for bug fixes with automatic retry:

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

Security Audit

Comprehensive security analysis combining CWE and STRIDE:

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

Team Collaboration

Parallel multi-agent execution for complex tasks:

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

Why Claude Forge?

Most developers either use Claude Code with no customization or spend hours assembling individual configs. Claude Forge gives you a production-ready setup in 5 minutes.

📦 What's Inside Claude Forge

📥 Claude Forge Installation Guide

As a Claude Code Plugin (v3.0.1+, partial coverage)

Since v3.0.1 claude-forge ships a standard Claude Code plugin manifest (.claude-plugin/plugin.json + .claude-plugin/marketplace.json). Install via the standard two-step flow:

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

Upgrade via /plugin update claude-forge (or the /plugin UI). What this path covers today (per Claude Code's current plugin loader): Commands + most Skills. Agents, Hooks, Rules, the 4 MCP servers, the statusLine, and settings.json env blocks still require the classic ./install.sh below. See docs/PLUGIN-VS-INSTALL-SH.md for the resource-by-resource matrix. Most users should keep ./install.sh as the primary install.

Prerequisites

macOS / Linux

git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
cd claude-forge
./install.sh                     # fresh install
# or
./install.sh --upgrade           # safe v2.1 → v3.0 migration (backup + diff preview)

The installer:

1. Checks dependencies (node, git, jq)
2. Initializes git submodules (CC CHIPS status bar)
3. Backs up existing ~/.claude/ if present
4. Creates symlinks for 7 directories + settings.json to ~/.claude/
5. Applies CC CHIPS custom overlay
6. Optionally installs MCP servers and external skills
7. Adds shell aliases (cc → claude, ccr → claude --resume)

Because it uses symlinks, git pull in the repo updates everything instantly. Use --upgrade after pulling v3.0 to apply MCP/settings migrations in place.

Windows

# Run PowerShell as Administrator
.\install.ps1

Windows uses file copies instead of symlinks. Re-run install.ps1 after git pull to update.

MCP Server Setup

v3.0.1 ships with 4 minimal defaults. Others are available opt-in via mcp-servers.optional.json. Full recipes: docs/MCP-MIGRATION.md. Rationale: docs/adr/ADR-001-mcp-default-set.md.

Customization

Override settings without modifying tracked files:

cp setup/settings.local.template.json ~/.claude/settings.local.json
vim ~/.claude/settings.local.json

settings.local.json merges on top of settings.json automatically.

🏗 Claude Forge Architecture

Skills vs Commands — skills/ host auto-invocable knowledge and reusable workflows (Claude discovers them via the description trigger). commands/ host explicit side-effect actions that the user times by typing /name. See docs/SKILLS-VS-COMMANDS.md for the policy.

graph TB
    subgraph REPO["claude-forge (git repo)"]
        A["agents/ (11)"]
        C["commands/ (33)"]
        S["skills/ (24)"]
        H["hooks/ (15)"]
        R["rules/ (9)"]
        SC["scripts/"]
        CC["cc-chips/"]
        K["knowledge/"]
        REF["reference/"]
        SET["settings.json"]
    end

    INSTALL["./install.sh"]
    REPO --> INSTALL

    subgraph HOME["~/.claude/ (symlinked)"]
        HA["agents/"]
        HC["commands/"]
        HS["skills/"]
        HH["hooks/"]
        HR["rules/"]
        HSC["scripts/"]
        HCC["cc-chips/"]
        HSET["settings.json"]
    end

    INSTALL -->|symlink| HOME

    CLAUDE["claude (CLI)"]
    HOME --> CLAUDE

    style REPO fill:#1a1a2e,stroke:#e94560,color:#fff
    style HOME fill:#0f3460,stroke:#16213e,color:#fff
    style INSTALL fill:#e94560,stroke:#fff,color:#fff
    style CLAUDE fill:#533483,stroke:#fff,color:#fff

claude-forge/
  ├── agents/                    Agent definitions (11 .md files, frontmatter v2)
  ├── cc-chips/                  Status bar submodule
  ├── cc-chips-custom/           Custom status bar overlay
  ├── commands/                  Slash commands (33 .md, 8 dirs moved to skills/)
  ├── docs/                      Screenshots, diagrams, policy docs (v3.0 guides)
  ├── hooks/                     Event-driven shell scripts (15)
  │   └── examples/              Opt-in .example samples for 21 lifecycle events (9)
  ├── knowledge/                 Knowledge base entries
  ├── reference/                 Reference docs (+ agent-schema.json)
  ├── rules/                     Auto-loaded rule files (9)
  ├── scripts/                   Utility scripts
  ├── setup/                     Installation guides + CLAUDE.md template
  ├── skills/                    Multi-step skill workflows (24, 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 (3.0.2)
  ├── .claude-plugin/marketplace.json  Marketplace entry (3.0.2)
  ├── settings.json              Claude Code settings (2026 fields)
  ├── MIGRATION.md               v2.1 → v3.0 migration guide (EN)
  ├── MIGRATION.ko.md            v2.1 → v3.0 migration guide (KO)
  ├── CONTRIBUTING.md            Contribution guide
  ├── SECURITY.md                Security policy
  └── LICENSE                    MIT License

🛡 Claude Code Automation Hooks

Security Hooks

Utility Hooks

Opt-in Examples (v3.0)

9 additional .example samples covering the newer lifecycle events (SessionEnd, PreCompact, SubagentStart/Stop, MessageStart/End, UserPromptReceived, and more) ship in hooks/examples/. The full 21-event catalog with recipes is in hooks/README.md. Rename *.example → *.sh and register in settings.json to activate.

🤖 Claude Code Agents

Each agent has a color in the UI for quick visual identification:

Opus Agents (6) -- Deep analysis & planning

Sonnet Agents (5) -- Fast execution & automation

Color Semantics

📋 All Claude Forge Commands

🧩 All Claude Forge Skills

Frequently Asked Questions

🤝 Contributing

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

Use Claude Forge? Show it!

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

Contributors

📄 License

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

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

_{Made with ❤️ by QJC (Quantum Jump Club)}