claude-forge

<picture> <source media="(prefers-color-scheme: dark)" srcset="docs/banner.jpg"> <source media="(prefers-color-scheme: light)" srcset="docs/banner-light.jpg"> <img src="docs/banner.jpg" alt="Claude Forge" width="100%"> </picture>

<p align="center"> <strong>Turn Claude Code into a full development environment</strong> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-blue?style=for-the-badge" alt="MIT License"></a> <a href="https://claude.com/claude-code"><img src="https://img.shields.io/badge/CLAUDE_CODE-%E2%89%A52.1.110-blueviolet?style=for-the-badge" alt="Claude Code"></a> <a href="https://github.com/sangrokjung/claude-forge/stargazers"><img src="https://img.shields.io/github/stars/sangrokjung/claude-forge?style=for-the-badge&color=yellow" alt="Stars"></a> <a href="https://github.com/sangrokjung/claude-forge/network/members"><img src="https://img.shields.io/github/forks/sangrokjung/claude-forge?style=for-the-badge&color=orange" alt="Forks"></a> <a href="https://github.com/sangrokjung/claude-forge/graphs/contributors"><img src="https://img.shields.io/github/contributors/sangrokjung/claude-forge?style=for-the-badge&color=green" alt="Contributors"></a> <a href="https://github.com/sangrokjung/claude-forge/commits/main"><img src="https://img.shields.io/github/last-commit/sangrokjung/claude-forge?style=for-the-badge" alt="Last Commit"></a> </p>

<p align="center"> <a href="#-whats-new-in-v30">What's New v3.0</a> &bull; <a href="#-quick-start">Quick Start</a> &bull; <a href="#-development-workflows">Workflows</a> &bull; <a href="#-whats-inside-claude-forge">What's Inside</a> &bull; <a href="#-claude-forge-installation-guide">Installation</a> &bull; <a href="#-claude-forge-architecture">Architecture</a> &bull; <a href="#-customization">Customization</a> &bull; <a href="README.ko.md">한국어</a> </p>

🎉 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):

```bash

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

<p align="center"> <img src="docs/workflow-pipeline.jpg" alt="Feature Development Workflow" width="720"> </p>

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

<p align="center"> <img src="docs/agent-teams.jpg" alt="Agent Teams Hub-and-Spoke" width="600"> </p>

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

<p align="center"> <img src="docs/features-grid.jpg" alt="Claude Forge Components" width="720"> </p>

📥 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.

<p align="center"> <img src="docs/architecture.jpg" alt="Symlink Architecture" width="720"> </p>

graph TB
    subgraph REPO["claude-forge (git repo)"]
        A["agents/ (11)"]
        C["commands/ (40)"]
        S["skills/ (15)"]
        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

<details> <summary><strong>Full Directory Tree</strong></summary>

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 (32 .md, 8 dirs moved to skills/)
  ├── docs/                      Screenshots, diagrams, policy docs (v3.0 guides)
  ├── hooks/                     Event-driven shell scripts (18)
  │   └── 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 (15+, 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

</details>

🛡 Claude Code Automation Hooks

Security Hooks

<p align="center"> <img src="docs/security-layers.jpg" alt="6-Layer Security Defense" width="480"> </p>

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

<details> <summary><strong>40 Commands (click to expand)</strong></summary>

</details>

🧩 All Claude Forge Skills

<details> <summary><strong>15 Skills (click to expand)</strong></summary>

</details>

Frequently Asked Questions

<details> <summary><strong>What is Claude Forge?</strong></summary>

Claude Forge is an open-source development environment for Claude Code. It bundles 11 specialized agents, 33 slash commands, 24 skill workflows, 15 automation hooks (+9 opt-in examples covering 21 lifecycle events), and 9 rule files into a single install. Think of it as "oh-my-zsh for Claude Code" -- it turns the basic Claude Code CLI into a fully equipped coding environment with built-in workflows for planning, TDD, security review, and deployment.

</details>

<details> <summary><strong>How is Claude Forge different from other Claude Code plugins?</strong></summary>

Most Claude Code plugins solve one problem at a time. Claude Forge is a complete development environment -- 11 agents (frontmatter v2), 33 commands, 24 skills, 15 hooks (+9 examples), and 9 rules that work together as a cohesive system. Instead of assembling individual plugins and configuring each one, Claude Forge gives you a pre-wired pipeline: /plan feeds into /tdd, which feeds into /code-review, which feeds into /handoff-verify, which feeds into /commit-push-pr. The 6-layer security hook system also runs automatically without extra configuration.

</details>

<details> <summary><strong>Is Claude Forge compatible with the official Claude Code plugin system?</strong></summary>

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.

</details>

<details> <summary><strong>How do I update Claude Forge?</strong></summary>

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.

</details>

<details> <summary><strong>Does Claude Forge work on Windows?</strong></summary>

Yes. Run install.ps1 in PowerShell as Administrator. Windows uses file copies instead of symlinks, so you need to re-run install.ps1 after each git pull to apply updates. All agents, commands, skills, and hooks work the same on Windows, macOS, and Linux.

</details>

<details> <summary><strong>What does /sync do?</strong></summary>

/sync synchronizes your project's memory and documentation. It pulls the latest changes from the remote repository and then syncs all project docs -- 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 ensure Claude has the latest context.

</details>

<details> <summary><strong>How does Claude Forge handle memory across sessions?</strong></summary>

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, workflow conventions loaded automatically each session.
3. MCP memory server -- A persistent knowledge graph that stores entities and relations across sessions.
4. Agent memory (~/.claude/agent-memory/) -- Core agents record learnings after each task, improving their recommendations over time through Self-Evolution.

Running /sync at session start ensures layers 1 and 2 are current. The MCP memory server (layer 3) and agent memory (layer 4) persist automatically.

</details>

🤝 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.

Contributors

<a href="https://github.com/sangrokjung/claude-forge/graphs/contributors"> <img src="https://contrib.rocks/image?repo=sangrokjung/claude-forge" /> </a>

📄 License

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

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

<p align="center"> _{Made with ❤️ by <a href="https://github.com/sangrokjung">QJC (Quantum Jump Club)</a>} </p>