claude-forge
oh-my-zsh for Claude Code — 16 agents, 35 commands, 33 skills, 22 hooks + 9 opt-in examples (21 events), 14 rules, 4 MCP in one install
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/sangrokjung-claude-forge)HTML
<a href="/listings/sangrokjung-claude-forge"><img src="/api/listings/sangrokjung-claude-forge/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
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](https://github.com/sangrokjung/claude-forge/stargazers) helps others find it.
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 38 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "claude-forge",
- "version": "4.3.0",
- "description": "oh-my-zsh for Claude Code — 16 agents, 35 commands, 33 skills, 22 hooks + 9 opt-in examples (21 events), 14 rules, 4 MCP in one install",
- "owner": {
- "name": "Sangrok Jung",
- "url": "https://github.com/sangrokjung"
- },
- "plugins": [
- {
- "name": "claude-forge",
- "description": "Production-grade development environment for Claude Code with 16 specialized agents, 35 slash commands, 33 skills, 22 hooks + 9 opt-in examples (21 events), 14 rules, and 4 MCP servers (playwright, context7, jina-reader, chrome-devtools pinned at 0.23.0). Includes TDD workflow, security review, code review, architecture analysis, build error resolution, Chrome DevTools Lighthouse / Core Web Vitals audits, and an adversarial verification loop (maker≠checker) with unattended API-error auto-resume, session relay, and Korean prose quality guardrails.",
- "version": "4.3.0",
- "author": {
- "name": "Sangrok Jung",
- "url": "https://github.com/sangrokjung"
- },
- "source": ".",
- "category": "development",
- "homepage": "https://github.com/sangrokjung/claude-forge",
- "tags": [
- "agents",
- "skills",
- "hooks",
- "tdd",
- "code-review",
- "security",
- "automation",
- "mcp-minimal",
- "mcp-chrome-devtools",
- "lighthouse",
- "performance",
- "adversarial-review"
- ]
- }
- ]
- }
README.md · README · 732 lines · 1 finding marked
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <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">
- <a href="https://sangrokjung.github.io/claude-forge/"><b>⚡ New here? Walk through setup in 60 seconds →</b></a>
- </p>
- <p align="center">
- <a href="README.md"><b>English</b></a> · <a href="README.ko.md">한국어</a> · <a href="README.zh.md">中文</a> · <a href="https://sangrokjung.github.io/claude-forge/">setup guide in 13 languages</a>
- </p>
- <p align="center">
- <strong>oh-my-zsh for Claude Code — one install, full professional kit</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="#what-is-claude-forge">What is it?</a> •
- <a href="#-why-bother">Why bother?</a> •
- <a href="#-install-in-minutes">Install</a> •
- <a href="#-whats-inside">What's inside</a> •
- <a href="#-how-to-use-it">How to use</a> •
- <a href="#-architecture">Architecture</a> •
- <a href="#-faq">FAQ</a> •
- <a href="README.ko.md">한국어</a>
- </p>
- > **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](hooks/README.md#running-a-hook-under-codex)).
- >
- > **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`](docs/VERIFICATION-LOOP.md). Also ships a reliability pack (API-error auto-resume, session relay across `/compact`, doom-loop guard — [`docs/RELIABILITY.md`](docs/RELIABILITY.md)), a debugging escalation chain, task-grade routing, and Korean prose quality guardrails. Details: [What's New in v4.0](#-whats-new-in-v40) · [MIGRATION.md](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](https://github.com/sangrokjung/claude-forge/issues/52), [#57](https://github.com/sangrokjung/claude-forge/issues/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](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:
- ```bash
- curl -fsSL https://raw.githubusercontent.com/sangrokjung/claude-forge/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 104 on GitHub
- ```
- Or if you prefer to clone first:
- ```bash
- 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](https://github.com/sangrokjung/claude-forge/stargazers) 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. |
- <details>
- <summary><strong>Full list: 16 Agents</strong></summary>
- #### 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. |
- </details>
- <details>
- <summary><strong>Full list: 35 Commands</strong></summary>
- #### 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. |
- </details>
- > 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](MIGRATION.md) Step 5. `install.sh` still creates compatibility symlinks under
- > `commands/` for them.
- <details>
- <summary><strong>Full list: 33 Skills</strong></summary>
- | 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. |
- </details>
- <details>
- <summary><strong>Full list: 22 Hooks (safety checks)</strong></summary>
- #### Security Hooks — block dangerous actions automatically
- <p align="center">
- <img src="docs/security-layers.jpg" alt="6-Layer Security Defense" width="480">
- </p>
- | 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`](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`](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`](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](#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`](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`](hooks/README.md#running-a-hook-under-codex) 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/`](hooks/examples/), one per event: PostCompact, PostToolUseFailure, PreCompact, StopFailure, SubagentStart, SubagentStop, TaskCreated, WorktreeCreate, WorktreeRemove. Full 21-event coverage; 27-event catalog: [`hooks/README.md`](hooks/README.md). To activate: rename `*.example` → `*.sh` and register in `settings.json`.
- </details>
- ---
- ## 🔄 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
- ```
- <p align="center">
- <img src="docs/workflow-pipeline.jpg" alt="Feature Development Workflow" width="720">
- </p>
- | 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
- ```
- <p align="center">
- <img src="docs/agent-teams.jpg" alt="Agent Teams Hub-and-Spoke" width="600">
- </p>
- ### 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`](docs/FIRST-STEPS.md) walks through your first
- session step by step, and [`docs/WORKFLOW-RECIPES.md`](docs/WORKFLOW-RECIPES.md) collects the
- command sequences for common jobs.
- ---
- ## 🏗 Architecture
- <p align="center">
- <img src="docs/architecture.jpg" alt="Symlink Architecture" width="720">
- </p>
- 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.
- ```mermaid
- 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](docs/SKILLS-VS-COMMANDS.md).
- <details>
- <summary><strong>Full Directory Tree</strong></summary>
- ```
- 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
- ```
- </details>
- ---
- ## 🔧 What's New in v4.0
- <details open>
- <summary><strong>v4.0 changes (click to collapse)</strong></summary>
- | 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`](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`](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](MIGRATION.md) for the full v3 → v4 upgrade guide.
- </details>
- ## 🔧 What's New in v3.0 (historical)
- <details>
- <summary><strong>v3.0 → v3.1.0 changes (click to expand)</strong></summary>
- ### 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](https://github.com/sangrokjung/claude-forge/releases/tag/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 `chrome-devtools-mcp@0.23.0`. |
- | **`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/`](hooks/examples/). |
- | **Subagent Frontmatter v2** | 10 optional fields: `isolation`, `background`, `memory`, `maxTurns`, `skills`, `mcpServers`, `effort`, `hooks`, `permissionMode`, `disallowedTools`. Schema: [`reference/agent-schema.json`](reference/agent-schema.json). |
- | **Skills/Commands Hybrid Policy** | Clear boundary documented at [`docs/SKILLS-VS-COMMANDS.md`](docs/SKILLS-VS-COMMANDS.md). |
- | **MCP Minimal (4 servers)** | Default set: `playwright` · `context7` · `jina-reader` · `chrome-devtools-mcp@0.23.0`. Legacy full set in [`mcp-servers.optional.json`](mcp-servers.optional.json). |
- | **CLAUDE.md Template** | New [`setup/CLAUDE.md.template`](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`](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`.
- </details>
- ---
- ## 🛠 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`](mcp-servers.optional.json). Full recipes: [`docs/MCP-MIGRATION.md`](docs/MCP-MIGRATION.md).
- ---
- ## ⚙️ Customization
- Override any setting without modifying tracked files:
- ```bash
- 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
- <details>
- <summary><strong>Do I need to know how to code to use Claude Forge?</strong></summary>
- 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.
- </details>
- <details>
- <summary><strong>What is Claude Code?</strong></summary>
- 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.
- </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 — 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.
- </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 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`](docs/RELIABILITY.md#platform-matrix) for the exact breakdown.
- </details>
- <details>
- <summary><strong>What does /sync do?</strong></summary>
- `/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.
- </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, 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.
- </details>
- ---
- ## 🤝 Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding agents, commands, skills, and hooks.
- ---
- ## Use Claude Forge? Show it!
- ```markdown
- [](https://github.com/sangrokjung/claude-forge)
- ```
- Add this badge to your project's README to let others know you use Claude Forge.
- ---
- ## ⭐ Star History
- [](https://www.star-history.com/#sangrokjung/claude-forge&Date)
- ---
- ## Contributors
- <a href="https://github.com/sangrokjung/claude-forge/graphs/contributors">
- <img src="https://contrib.rocks/image?repo=sangrokjung/claude-forge" />
- </a>
- ---
- ## 📄 License
- [MIT](LICENSE) — use it, fork it, build on it.
- If Claude Forge improved your workflow, a [star](https://github.com/sangrokjung/claude-forge/stargazers) helps others find it too.
- ---
- <p align="center">
- <sub>Made with ❤️ by <a href="https://github.com/sangrokjung">QJC (Quantum Jump Club)</a></sub>
- </p>
.claude-plugin/plugin.json · Bundled script · 33 lines · 1 finding marked
- {
- "name": "claude-forge",
- "version": "4.3.0",
- "description": "oh-my-zsh for Claude Code — 16 agents, 35 commands, 33 skills, 22 hooks + 9 examples (21 events), 14 rules, 4 MCP (minimal: playwright, context7, jina-reader, chrome-devtools@0.23.0). Adversarial verification loop (maker≠checker), unattended API-error auto-resume, session relay, and Korean prose quality guardrails. One-line install: curl -fsSL https://raw.githubusercontent.com/sangrokjung/claude-forge/main/install.sh | bash",
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 4 on GitHub
- "author": {
- "name": "Sangrok Jung",
- "url": "https://github.com/sangrokjung"
- },
- "repository": "https://github.com/sangrokjung/claude-forge",
- "homepage": "https://github.com/sangrokjung/claude-forge",
- "license": "MIT",
- "keywords": [
- "claude-code",
- "development-environment",
- "agents",
- "skills",
- "hooks",
- "tdd",
- "code-review",
- "security",
- "automation",
- "oh-my-zsh",
- "hooks-22",
- "skills-commands-hybrid",
- "mcp-minimal",
- "adversarial-review",
- "v4"
- ],
- "engines": {
- "claude-code": ">=2.1.110"
- },
- "minClaudeCodeVersion": "2.1.110"
- }
hooks/remote-command-guard.sh · Bundled script · 213 lines · 1 finding marked
- #!/bin/bash
- # Remote Command Guard - PreToolUse Hook
- # 원격 Claude Code 세션에서 위험한 Bash 명령을 차단
- #
- # Hook trigger: PreToolUse, matcher: Bash
- # Exit codes: 0 = 허용, 2 = 차단
- #
- # 차단 범주:
- # 1. 파괴적 삭제 (rm -rf /, rm -rf ~, rm -rf *)
- # 2. 환경변수/시크릿 유출 (env, printenv, echo $SECRET 등)
- # 3. 경로 순회 (/etc/passwd, /etc/shadow 등)
- # 4. 외부 통신 (curl, wget, nc, ncat 등)
- # 5. 권한 변경 (chmod 777, chown, mount 등)
- # 6. 프로세스 종료 (kill -9, pkill 등)
- # 7. 명령 주입 (eval, exec 등)
- # 원격 세션이 아니면 검사 건너뜀
- if [[ -z "${OPENCLAW_SESSION_ID:-}" ]]; then
- exit 0
- fi
- # stdin에서 JSON 읽기
- INPUT=$(cat)
- # 명령어 추출 (python3 -c + 작은따옴표로 셸 확장 방지)
- COMMAND=$(echo "$INPUT" | python3 -c '
- import sys, json
- data = json.load(sys.stdin)
- print(data.get("tool_input", {}).get("command", ""))
- ' 2>/dev/null)
- if [[ -z "$COMMAND" ]]; then
- exit 0
- fi
- # 환경변수로 명령어 전달 → heredoc으로 Python 검사 로직 주입
- export _GUARD_CMD="$COMMAND"
- python3 << 'GUARD_SCRIPT'
- import os
- import sys
- import re
- command = os.environ.get("_GUARD_CMD", "")
- if not command:
- sys.exit(0)
- # 명령어 정규화 (여러 공백 → 단일 공백)
- cmd = re.sub(r'\s+', ' ', command.strip())
- cmd_lower = cmd.lower()
- blocked_reason = None
- # === 1. 파괴적 삭제 ===
- # rm -rf / , rm -rf ~ , rm -rf * 등 광범위 삭제만 차단
- Dismissed after review: Runs `rm -rf` against a root or home-directory path
- Line 54 on GitHub
- # rm /tmp/specific-file.txt 같은 특정 파일 삭제는 허용
- destructive_patterns = [
- r'\brm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s', # rm -rf, rm -rfi 등
- r'\brm\s+-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*\s', # rm -fr, rm -fri 등
- r'\brm\b.*\s+/$', # rm / (루트)
- r'\brm\b.*\s+/\s', # rm / something
- r'\brm\b.*\s+~/?(\s|$)', # rm ~ 또는 rm ~/
- r'\brm\b.*\s+\*(\s|$)', # rm * (현재 디렉토리 전체)
- r'\bmkfs\b',
- r'\bdd\s+.*of=/dev/',
- r'\b:\s*\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;',
- ]
- for pat in destructive_patterns:
- if re.search(pat, cmd_lower):
- blocked_reason = "파괴적 삭제 명령 감지"
- break
- # === 2. 환경변수/시크릿 유출 ===
- # 시크릿 패턴은 원본 cmd에 re.IGNORECASE로 매칭 (환경변수명 대소문자 보존)
- if not blocked_reason:
- secret_patterns = [
- r'\b(env|printenv|set)\s*$',
- r'\b(env|printenv|set)\s*\|',
- r'\becho\s+.*\$[A-Z_]*KEY\b',
- r'\becho\s+.*\$[A-Z_]*SECRET\b',
- r'\becho\s+.*\$[A-Z_]*TOKEN\b',
- r'\becho\s+.*\$[A-Z_]*PASSWORD\b',
- r'\becho\s+.*\$[A-Z_]*PASSWD\b',
- r'\becho\s+.*\$[A-Z_]*API\b',
- r'\becho\s+.*\$[A-Z_]*CREDENTIAL\b',
- r'\becho\s+.*\$(AWS_|OPENAI_|ANTHROPIC_|TELEGRAM_|GITHUB_|SUPABASE_)',
- r'\bcat\s+.*\.env\b',
- r'\bcat\s+.*\.netrc\b',
- r'\bcat\s+.*credentials\b',
- r'\bcat\s+.*/\.ssh/',
- r'\bexport\s+-p\s*$',
- r'\bexport\s+-p\s*\|',
- r'\bcat\s+.*seed\.txt\b',
- r'\bcat\s+.*wallet\.json\b',
- r'\bcat\s+.*keystore\b',
- ]
- for pat in secret_patterns:
- if re.search(pat, cmd, re.IGNORECASE):
- blocked_reason = "시크릿/환경변수 유출 시도 감지"
- break
- # === 3. 경로 순회 ===
- if not blocked_reason:
- path_traversal_patterns = [
- r'/etc/passwd',
- r'/etc/shadow',
- r'/etc/sudoers',
- r'/etc/master\.passwd',
- r'\.\./(\.\./)*(etc|proc|sys|dev)/',
- r'/proc/self/',
- r'/proc/\d+/',
- r'/sys/class/',
- ]
- for pat in path_traversal_patterns:
- if re.search(pat, cmd_lower):
- blocked_reason = "민감 시스템 경로 접근 감지"
- break
- # === 4. 외부 통신 ===
- if not blocked_reason:
- network_patterns = [
- r'\bcurl\s',
- r'\bwget\s',
- r'\bnc\s',
- r'\bncat\s',
- r'\bnetcat\s',
- r'\btelnet\s',
- r'\bssh\s',
- r'\bscp\s',
- r'\brsync\s.*:',
- r'\bftp\s',
- r'\bsftp\s',
- r'\bsocat\s',
- r'\bpython3?\s+-m\s+http\.server',
- r'\bphp\s+-S\s',
- r'\bnpm\s+publish\b',
- r'\bnpx\s.*ngrok',
- ]
- # localhost/127.0.0.1 대상 curl/wget은 허용 (개발용)
- is_local = bool(re.search(
- r'\bcurl\s+.*\b(localhost|127\.0\.0\.1|0\.0\.0\.0)\b', cmd_lower
- ))
- if not is_local:
- for pat in network_patterns:
- if re.search(pat, cmd_lower):
- blocked_reason = "외부 네트워크 통신 시도 감지"
- break
- # === 5. 권한 변경 ===
- if not blocked_reason:
- permission_patterns = [
- r'\bchmod\s+777\b',
- r'\bchmod\s+666\b',
- r'\bchmod\s+[0-7]*[67][0-7]{2}\b.*/(etc|usr|var|sys)',
- r'\bchown\s',
- r'\bmount\s',
- r'\bumount\s',
- r'\bsudo\s',
- r'\bsu\s+-?\s',
- r'\bdscl\s',
- ]
- for pat in permission_patterns:
- if re.search(pat, cmd_lower):
- blocked_reason = "권한 변경 명령 감지"
- break
- # === 6. 프로세스 종료 ===
- if not blocked_reason:
- process_patterns = [
- r'\bkill\s+-9\b',
- r'\bkill\s+-KILL\b',
- r'\bkill\s+-SIGKILL\b',
- r'\bkillall\s',
- r'\bpkill\s',
- r'\bxkill\b',
- r'\bshutdown\b',
- r'\breboot\b',
- r'\bhalt\b',
- r'\binit\s+[06]\b',
- ]
- for pat in process_patterns:
- if re.search(pat, cmd_lower):
- blocked_reason = "프로세스 종료/시스템 제어 명령 감지"
- break
- # === 7. 명령 주입 ===
- if not blocked_reason:
- injection_patterns = [
- r'\beval\s',
- r'\bexec\s',
- r'\bsource\s+/dev/',
- r'\bbash\s+-c\s.*\$\(',
- r'\bsh\s+-c\s.*\$\(',
- r'`[^`]*\$\([^)]+\)[^`]*`',
- r'\|\s*sh\b',
- r'\|\s*bash\b',
- r'\|\s*zsh\b',
- r'>\s*/dev/sd[a-z]',
- r'>\s*/dev/nvme',
- r'\bbase64\s+-d\s*\|\s*(sh|bash|zsh)',
- ]
- for pat in injection_patterns:
- if re.search(pat, cmd_lower):
- blocked_reason = "명령 주입 패턴 감지"
- break
- if blocked_reason:
- safe_cmd = cmd[:200]
- print(f"BLOCKED: {blocked_reason}", file=sys.stderr)
- print(f"Command: {safe_cmd}", file=sys.stderr)
- sys.exit(2)
- sys.exit(0)
- GUARD_SCRIPT
install.sh · Bundled script · 754 lines · 1 finding marked
- #!/bin/bash
- set -e
- REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
- CLAUDE_DIR="$HOME/.claude"
- # Defaults
- UPGRADE_MODE=0
- DRY_RUN=0
- # Usage banner
- print_usage_and_exit() {
- cat << USAGE
- Usage: install.sh [OPTIONS]
- Options:
- --upgrade Upgrade existing installation to v4.0 (preserves symlinks,
- refreshes targets, prints breaking-change guidance).
- --dry-run Show what would change without modifying files.
- -h, --help Show this help message.
- Examples:
- ./install.sh # Fresh install
- ./install.sh --upgrade # Upgrade v2.x -> v4.0 in place
- ./install.sh --dry-run # Preview changes
- ./install.sh --upgrade --dry-run
- Breaking changes since v2.1, introduced in v3.0 (see MIGRATION.md):
- - MCP servers: 6 -> 3 (playwright, context7, jina-reader)
- - Hooks: 5 events -> 21 (opt-in via hooks/examples/)
- - Subagent frontmatter: v2 optional fields
- - Skills/Commands: hybrid policy (docs/SKILLS-VS-COMMANDS.md)
- USAGE
- exit 0
- }
- # Parse arguments
- while [ $# -gt 0 ]; do
- case "${1:-}" in
- --upgrade)
- UPGRADE_MODE=1
- shift
- ;;
- --dry-run)
- DRY_RUN=1
- shift
- ;;
- -h|--help)
- print_usage_and_exit
- ;;
- *)
- echo "Unknown option: $1" >&2
- echo "Run './install.sh --help' for usage." >&2
- exit 1
- ;;
- esac
- done
- # Detect platform
- detect_platform() {
- if [[ "$OSTYPE" == "darwin"* ]]; then
- PLATFORM="macos"
- ARCH="$(uname -m)"
- elif grep -qEi "(Microsoft|WSL)" /proc/version 2>/dev/null || [ -f /proc/sys/fs/binfmt_misc/WSLInterop ]; then
- PLATFORM="wsl"
- ARCH="$(uname -m)"
- elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
- PLATFORM="linux"
- ARCH="$(uname -m)"
- else
- PLATFORM="unknown"
- ARCH="$(uname -m)"
- fi
- }
- detect_platform
- cat << 'BANNER'
- ╔═╗┬ ┌─┐┬ ┬┌┬┐┌─┐ ╔═╗┌─┐┬─┐┌─┐┌─┐
- ║ │ ├─┤│ │ ││├┤ ╠╣ │ │├┬┘│ ┬├┤
- ╚═╝┴─┘┴ ┴└─┘─┴┘└─┘ ╚ └─┘┴└─└─┘└─┘
- Production-grade Claude Code Framework
- github.com/sangrokjung/claude-forge
- BANNER
- echo "Platform: $PLATFORM ($ARCH)"
- echo ""
- # Colors
- RED='\033[0;31m'
- GREEN='\033[0;32m'
- YELLOW='\033[1;33m'
- NC='\033[0m' # No Color
- # Upgrade banner (printed when --upgrade is set)
- print_upgrade_banner() {
- echo "=========================================="
- echo " claude-forge v4.0 Upgrade"
- echo "=========================================="
- echo ""
- echo " Breaking changes since v2.1:"
- echo " - MCP: 6 servers -> 3 (playwright, context7, jina-reader)"
- echo " - Removed: memory, exa, github, fetch"
- echo " - Recipes: docs/MCP-MIGRATION.md"
- echo " - Hooks: 5 events -> 21 (opt-in via hooks/examples/)"
- echo " - Subagent frontmatter: v2 optional fields"
- echo " - Skills/Commands: hybrid policy (docs/SKILLS-VS-COMMANDS.md)"
- echo ""
- if [ "$DRY_RUN" -eq 1 ]; then
- echo -e " ${YELLOW}[DRY-RUN] No files will be modified.${NC}"
- echo ""
- fi
- }
- # v3.0 skills/commands 호환 링크 (v2.1에서 commands로 제공되던 항목 일부가
- # v3.0에서 skills로 이동한 경우에 대한 하위 호환)
- create_v3_compat_links() {
- local target_base="$CLAUDE_DIR"
- local created=0
- # v2.1 경로 -> v3.0 경로 매핑
- # v2.1의 commands/ 디렉토리형 skill(8개)이 v3.0에서 skills/로 이전됨.
- # 기존 참조를 깨지 않도록 심볼릭 링크로 호환성 유지 (2027-04-01까지).
- local mappings=(
- "commands/debugging-strategies:skills/debugging-strategies"
- "commands/dependency-upgrade:skills/dependency-upgrade"
- "commands/evaluating-code-models:skills/evaluating-code-models"
- "commands/evaluating-llms-harness:skills/evaluating-llms-harness"
- "commands/extract-errors:skills/extract-errors"
- "commands/security-compliance:skills/security-compliance"
- "commands/stride-analysis-patterns:skills/stride-analysis-patterns"
- "commands/summarize:skills/summarize"
- )
- for mapping in "${mappings[@]}"; do
- local old_path="${mapping%%:*}"
- local new_path="${mapping##*:}"
- local new_target="$REPO_DIR/$new_path"
- local old_link="$target_base/$old_path"
- if [ -e "$new_target" ] && [ ! -e "$old_link" ]; then
- if [ "$DRY_RUN" -eq 1 ]; then
- echo " [DRY-RUN] would create compat link: $old_path -> $new_path"
- else
- mkdir -p "$(dirname "$old_link")"
- ln -sf "$new_target" "$old_link" 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} compat link: $old_path -> $new_path" && \
- created=$((created + 1)) || true
- fi
- fi
- done
- if [ "$created" -eq 0 ] && [ "$DRY_RUN" -ne 1 ]; then
- echo " (no compat links needed)"
- fi
- }
- # Upgrade-mode summary
- print_upgrade_summary() {
- echo ""
- echo "=========================================="
- echo " Upgrade Summary"
- echo "=========================================="
- echo " Version : v4.1.0"
- echo " Mode : $([ "$DRY_RUN" -eq 1 ] && echo 'dry-run' || echo 'applied')"
- echo " Repo : $REPO_DIR"
- echo " Target : $CLAUDE_DIR"
- echo ""
- echo " Expected counts:"
- echo " - 16 agents, 33 skills (24 native + 8 moved from commands + 1 vendored: loop-forge), 35 commands, 14 rules, 22 hooks + 9 opt-in examples"
- echo ""
- echo " Next steps:"
- echo " 1. Review MIGRATION.md for detailed changes"
- echo " 2. Opt-in new hooks from hooks/examples/ as needed"
- echo " 3. Run 'claude mcp list' to verify 3 MCP servers"
- echo ""
- }
- # 1. Check dependencies
- check_deps() {
- echo "Checking dependencies..."
- local missing=()
- command -v node >/dev/null || missing+=("node")
- command -v jq >/dev/null || missing+=("jq")
- command -v git >/dev/null || missing+=("git")
- if [ ${#missing[@]} -gt 0 ]; then
- echo -e "${RED}Missing dependencies: ${missing[*]}${NC}"
- echo ""
- case "$PLATFORM" in
- macos)
- echo "Install with: brew install ${missing[*]}"
- ;;
- wsl|linux)
- echo "Install with: sudo apt install ${missing[*]}"
- echo " or: curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -"
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 199 on GitHub
- ;;
- *)
- echo "Install with your package manager"
- ;;
- esac
- echo ""
- echo -e "${YELLOW}Need help? github.com/sangrokjung/claude-forge/issues${NC}"
- exit 1
- fi
- echo -e "${GREEN}All dependencies satisfied${NC}"
- }
- # 2. Initialize git submodules (cc-chips)
- init_submodules() {
- echo ""
- echo "Initializing git submodules..."
- cd "$REPO_DIR"
- git submodule update --init --recursive 2>/dev/null && \
- echo -e "${GREEN}Submodules initialized (cc-chips)${NC}" || \
- echo -e "${YELLOW}Submodule init skipped (may already be initialized)${NC}"
- }
- # 3. Backup existing config
- backup() {
- if [ -d "$CLAUDE_DIR" ]; then
- local backup_dir="$CLAUDE_DIR.backup.$(date +%Y%m%d_%H%M%S)"
- echo ""
- echo -e "${YELLOW}Existing ~/.claude found${NC}"
- # Upgrade mode: skip wholesale move, just refresh symlinks in place
- if [ "$UPGRADE_MODE" -eq 1 ]; then
- echo " Upgrade mode: preserving $CLAUDE_DIR (symlinks will be refreshed)."
- return 0
- fi
- read -p "Backup to $backup_dir? (y/n) " -n 1 -r
- echo ""
- if [[ $REPLY =~ ^[Yy]$ ]]; then
- if [ "$DRY_RUN" -eq 1 ]; then
- echo " [DRY-RUN] would mv $CLAUDE_DIR -> $backup_dir"
- else
- mv "$CLAUDE_DIR" "$backup_dir"
- echo -e "${GREEN}Backed up to $backup_dir${NC}"
- fi
- else
- echo "Skipping backup. Existing files may be overwritten."
- fi
- fi
- }
- # 4. Create symlinks (or copies on WSL cross-filesystem)
- link_files() {
- echo ""
- # WSL: if repo is on Windows filesystem (/mnt/c/...), use copies instead of symlinks
- local use_copy=false
- if [[ "$PLATFORM" == "wsl" ]] && [[ "$REPO_DIR" == /mnt/* ]]; then
- echo -e "${YELLOW}WSL detected with Windows filesystem path. Using copies instead of symlinks.${NC}"
- echo " Tip: Clone repo to ~/claude-forge for symlink support."
- use_copy=true
- fi
- if [ "$use_copy" = true ]; then
- echo "Copying configuration files..."
- else
- echo "Creating symlinks..."
- fi
- if [ "$DRY_RUN" -eq 1 ]; then
- echo " [DRY-RUN] would mkdir -p $CLAUDE_DIR"
- else
- mkdir -p "$CLAUDE_DIR"
- fi
- # Directories
- # NOTE: cc-chips is a git submodule; if the user cloned without
- # --recurse-submodules the directory exists but is empty, which would
- # create a broken symlink that statusLine would then dereference. Skip
- # with a one-line hint in that case so the rest of the install still
- # succeeds.
- for dir in agents rules commands scripts skills hooks libs reference cc-chips cc-chips-custom; do
- if [ -d "$REPO_DIR/$dir" ]; then
- if [ "$dir" = "cc-chips" ] && [ -z "$(ls -A "$REPO_DIR/$dir" 2>/dev/null)" ]; then
- echo -e " ${YELLOW}!${NC} Skipping cc-chips/: submodule not initialized."
- echo " Run: git submodule update --init cc-chips"
- echo " (statusLine chip renderer will be disabled until then.)"
- continue
- fi
- if [ "$DRY_RUN" -eq 1 ]; then
- echo " [DRY-RUN] would refresh $dir/"
- continue
- fi
- rm -rf "$CLAUDE_DIR/$dir" 2>/dev/null || true
- if [ "$use_copy" = true ]; then
- cp -r "$REPO_DIR/$dir" "$CLAUDE_DIR/$dir"
- echo " Copied: $dir/"
- else
- ln -sf "$REPO_DIR/$dir" "$CLAUDE_DIR/$dir"
- echo " Linked: $dir/"
- fi
- fi
- done
- # Files
- for file in settings.json; do
- if [ -f "$REPO_DIR/$file" ]; then
- if [ "$DRY_RUN" -eq 1 ]; then
- echo " [DRY-RUN] would refresh $file"
- continue
- fi
- rm -f "$CLAUDE_DIR/$file" 2>/dev/null || true
- if [ "$use_copy" = true ]; then
- cp "$REPO_DIR/$file" "$CLAUDE_DIR/$file"
- echo " Copied: $file"
- else
- ln -sf "$REPO_DIR/$file" "$CLAUDE_DIR/$file"
- echo " Linked: $file"
- fi
- fi
- done
- }
- # 4b. Validate mcp-servers.json for v3.0 (3 core entries)
- validate_mcp_v3() {
- local mcp_json="$REPO_DIR/mcp-servers.json"
- if [ ! -f "$mcp_json" ] || ! command -v jq >/dev/null; then
- return 0
- fi
- echo ""
- echo "Validating mcp-servers.json (v3.0 minimal profile)..."
- # v3.0 schema uses `.servers.<name>`; legacy v2.x used `.install_commands.<name>`
- local expected=("playwright" "context7" "jina-reader")
- local missing=()
- for s in "${expected[@]}"; do
- local present=0
- if jq -e --arg s "$s" '.servers[$s] // empty' "$mcp_json" >/dev/null 2>&1; then
- present=1
- elif jq -e --arg s "$s" '.install_commands[$s] // empty' "$mcp_json" >/dev/null 2>&1; then
- present=1
- fi
- [ "$present" -eq 0 ] && missing+=("$s")
- done
- local server_count
- server_count=$(jq -r '.servers | length // 0' "$mcp_json" 2>/dev/null || echo 0)
- if [ ${#missing[@]} -eq 0 ]; then
- echo -e " ${GREEN}✓${NC} v3.0 core MCP entries present (3/3, total=$server_count)"
- else
- echo -e " ${YELLOW}!${NC} Missing v3.0 MCP entries: ${missing[*]}"
- echo " See docs/MCP-MIGRATION.md for remediation."
- fi
- }
- # 5. Apply CC CHIPS custom overlay
- apply_cc_chips_custom() {
- local custom_dir="$REPO_DIR/cc-chips-custom"
- if [ -d "$custom_dir" ]; then
- echo ""
- echo "Applying CC CHIPS custom overlay..."
- if [ "$DRY_RUN" -eq 1 ]; then
- echo " [DRY-RUN] would overlay engine.sh + themes/*.sh"
- return 0
- fi
- local target="$CLAUDE_DIR/cc-chips"
- if [ -f "$custom_dir/engine.sh" ] && [ -d "$target" ]; then
- cp "$custom_dir/engine.sh" "$target/engine.sh"
- chmod +x "$target/engine.sh"
- echo -e " ${GREEN}✓${NC} engine.sh (model detection + session ID + cache stats)"
- fi
- if [ -d "$custom_dir/themes" ] && [ -d "$target/themes" ]; then
- cp "$custom_dir/themes/"*.sh "$target/themes/" 2>/dev/null
- echo -e " ${GREEN}✓${NC} themes/ (stats chip colors)"
- fi
- echo -e "${GREEN}CC CHIPS custom overlay applied!${NC}"
- fi
- }
- # 6. Install MCP servers
- install_mcp_servers() {
- echo ""
- echo "Installing MCP servers..."
- # Check if claude CLI is available
- if ! command -v claude >/dev/null; then
- echo -e "${YELLOW}Claude CLI not found. Skipping MCP server installation.${NC}"
- echo "Install Claude CLI first, then re-run this script."
- return 0
- fi
- read -p "Install recommended MCP servers? (y/n) " -n 1 -r
- echo ""
- if [[ ! $REPLY =~ ^[Yy]$ ]]; then
- echo "Skipping MCP server installation."
- return 0
- fi
- # Read install commands from mcp-servers.json if available
- local mcp_json="$REPO_DIR/mcp-servers.json"
- if [ -f "$mcp_json" ] && command -v jq >/dev/null; then
- echo " Installing from mcp-servers.json..."
- # Core servers (no API key required)
- local core_servers=("context7" "sequential-thinking" "memory" "youtube-transcript" "remotion" "playwright" "desktop-commander")
- for server in "${core_servers[@]}"; do
- local cmd
- cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
- if [ -n "$cmd" ]; then
- echo " Installing $server..."
- eval "$cmd" 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} $server" || \
- echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
- fi
- done
- # Optional servers
- echo ""
- echo -e "${YELLOW}Optional servers (may require authentication):${NC}"
- local optional_servers=("exa" "gmail" "google-calendar" "n8n-mcp" "hyperbrowser" "stitch" "sentry" "supabase" "github")
- for server in "${optional_servers[@]}"; do
- local cmd
- cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
- if [ -n "$cmd" ]; then
- read -p " Install $server? (y/n) " -n 1 -r
- echo ""
- if [[ $REPLY =~ ^[Yy]$ ]]; then
- eval "$cmd" 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} $server" || \
- echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
- fi
- fi
- done
- # Korean public data servers
- echo ""
- read -p " Install Korean public data servers (NTS, NPS, PPS, FSC, MSDS)? (y/n) " -n 1 -r
- echo ""
- if [[ $REPLY =~ ^[Yy]$ ]]; then
- for server in "data-go-nts" "data-go-nps" "data-go-pps" "data-go-fsc" "data-go-msds"; do
- local cmd
- cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
- if [ -n "$cmd" ]; then
- eval "$cmd" 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} $server" || \
- echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
- fi
- done
- fi
- # Financial data servers
- echo ""
- read -p " Install financial data servers (CoinGecko, Alpha Vantage, FRED, Korea Stock)? (y/n) " -n 1 -r
- echo ""
- if [[ $REPLY =~ ^[Yy]$ ]]; then
- for server in "coingecko" "alpha-vantage" "fred" "korea-stock"; do
- local cmd
- cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
- if [ -n "$cmd" ]; then
- eval "$cmd" 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} $server" || \
- echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
- fi
- done
- fi
- else
- # Fallback: minimal install without mcp-servers.json
- echo " Installing core MCP servers..."
- claude mcp add context7 -- npx -y @upstash/context7-mcp 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} context7" || echo -e " ${YELLOW}!${NC} context7"
- claude mcp add playwright -- npx @playwright/mcp@latest 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} playwright" || echo -e " ${YELLOW}!${NC} playwright"
- claude mcp add memory -- npx -y @modelcontextprotocol/server-memory 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} memory" || echo -e " ${YELLOW}!${NC} memory"
- claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} sequential-thinking" || echo -e " ${YELLOW}!${NC} sequential-thinking"
- fi
- echo ""
- echo -e "${GREEN}MCP server installation complete!${NC}"
- echo "Run 'claude mcp list' to verify installed servers."
- }
- # 7. Install external skills (npx skills)
- install_external_skills() {
- echo ""
- echo "Installing external skills..."
- if ! command -v npx >/dev/null; then
- echo -e "${YELLOW}npx not found. Skipping external skills installation.${NC}"
- return 0
- fi
- read -p "Install external skills (Superpowers, Humanizer, UI/UX Pro Max, Find Skills)? (y/n) " -n 1 -r
- echo ""
- if [[ ! $REPLY =~ ^[Yy]$ ]]; then
- echo "Skipping external skills installation."
- return 0
- fi
- echo " Installing Superpowers (14 skills)..."
- npx -y skills add obra/superpowers -y -g 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} superpowers" || echo -e " ${YELLOW}!${NC} superpowers (failed)"
- echo " Installing Humanizer..."
- npx -y skills add blader/humanizer -y -g 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} humanizer" || echo -e " ${YELLOW}!${NC} humanizer (failed)"
- echo " Installing UI/UX Pro Max..."
- npx -y skills add nextlevelbuilder/ui-ux-pro-max-skill -y -g 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} ui-ux-pro-max" || echo -e " ${YELLOW}!${NC} ui-ux-pro-max (failed)"
- echo " Installing Find Skills..."
- npx -y skills add vercel-labs/skills -y -g 2>/dev/null && \
- echo -e " ${GREEN}✓${NC} find-skills" || echo -e " ${YELLOW}!${NC} find-skills (failed)"
- echo ""
- echo -e "${GREEN}External skills installation complete!${NC}"
- }
- # 8. Setup shell aliases
- setup_shell_aliases() {
- echo ""
- echo "Setting up shell aliases..."
- local shell_rc=""
- if [ -n "$ZSH_VERSION" ] || [ -f "$HOME/.zshrc" ]; then
- shell_rc="$HOME/.zshrc"
- elif [ -f "$HOME/.bashrc" ]; then
- shell_rc="$HOME/.bashrc"
- fi
- if [ -z "$shell_rc" ]; then
- echo -e "${YELLOW}No .zshrc or .bashrc found. Skipping aliases.${NC}"
- return 0
- fi
- local marker="# Claude Code aliases"
- if grep -q "$marker" "$shell_rc" 2>/dev/null; then
- echo -e " ${GREEN}✓${NC} Aliases already configured in $(basename "$shell_rc")"
- return 0
- fi
- cat >> "$shell_rc" << 'ALIASES'
- # Claude Code aliases
- alias cc='claude'
- alias ccr='claude --resume'
- ALIASES
- echo -e " ${GREEN}✓${NC} Added aliases to $(basename "$shell_rc")"
- echo " cc → claude"
- echo " ccr → claude --resume"
- }
- # 9. Verify installation
- verify() {
- echo ""
- echo "Verifying installation..."
- local errors=0
- for item in agents rules commands scripts skills cc-chips cc-chips-custom hooks libs reference settings.json; do
- if [ -L "$CLAUDE_DIR/$item" ] && [ ! -e "$CLAUDE_DIR/$item" ]; then
- echo -e " ${RED}✗${NC} $item (broken symlink)"
- errors=$((errors + 1))
- elif [ -L "$CLAUDE_DIR/$item" ] || [ -e "$CLAUDE_DIR/$item" ]; then
- echo -e " ${GREEN}✓${NC} $item"
- else
- echo -e " ${RED}✗${NC} $item (not found)"
- errors=$((errors + 1))
- fi
- done
- return $errors
- }
- # 10. Write forge metadata
- write_meta() {
- echo ""
- echo "Writing forge metadata..."
- # install_mode 판단: agents가 symlink이면 symlink, 아니면 copy
- local install_mode="symlink"
- if [ ! -L "$CLAUDE_DIR/agents" ] && [ -d "$CLAUDE_DIR/agents" ]; then
- install_mode="copy"
- fi
- # plugin.json에서 버전 읽기
- local version="1.0.0"
- if [ -f "$REPO_DIR/.claude-plugin/plugin.json" ] && command -v jq >/dev/null; then
- version=$(jq -r '.version // "1.0.0"' "$REPO_DIR/.claude-plugin/plugin.json")
- fi
- # git 정보
- local git_commit=""
- local remote_url=""
- if command -v git >/dev/null && [ -d "$REPO_DIR/.git" ]; then
- git_commit=$(cd "$REPO_DIR" && git rev-parse --short HEAD 2>/dev/null || echo "")
- remote_url=$(cd "$REPO_DIR" && git remote get-url origin 2>/dev/null || echo "")
- fi
- local now
- now=$(date +"%Y-%m-%dT%H:%M:%S%z" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%S")
- # 기존 메타파일이 있으면 installed_at 보존
- local installed_at="$now"
- if [ -f "$CLAUDE_DIR/.forge-meta.json" ] && command -v jq >/dev/null; then
- local prev_installed
- prev_installed=$(jq -r '.installed_at // ""' "$CLAUDE_DIR/.forge-meta.json")
- if [ -n "$prev_installed" ] && [ "$prev_installed" != "null" ]; then
- installed_at="$prev_installed"
- fi
- fi
- # jq로 안전하게 JSON 생성 (경로 인젝션 방지)
- jq -n \
- --arg repo_path "$REPO_DIR" \
- --arg install_mode "$install_mode" \
- --arg installed_at "$installed_at" \
- --arg updated_at "$now" \
- --arg version "$version" \
- --arg git_commit "$git_commit" \
- --arg remote_url "$remote_url" \
- --arg platform "$PLATFORM" \
- '{
- repo_path: $repo_path,
- install_mode: $install_mode,
- installed_at: $installed_at,
- updated_at: $updated_at,
- version: $version,
- git_commit: $git_commit,
- remote_url: $remote_url,
- platform: $platform
- }' > "$CLAUDE_DIR/.forge-meta.json"
- chmod 600 "$CLAUDE_DIR/.forge-meta.json"
- echo -e " ${GREEN}✓${NC} .forge-meta.json"
- }
- # 11. Install work tracker (local usage log; remote sync is opt-in)
- install_work_tracker() {
- local wt_script="$REPO_DIR/setup/work-tracker-install.sh"
- if [ -f "$wt_script" ]; then
- echo ""
- # Remote sync needs scripts/work-tracker-sync.sh, which is not shipped: the
- # backend differs per user. Without it the hooks still log locally to
- # ~/.claude/work-log/buffer.jsonl, so do not promise a sync we cannot install.
- read -p "Install Work Tracker (logs Claude Code usage to ~/.claude/work-log)? (y/n) " -n 1 -r
- echo ""
- if [[ $REPLY =~ ^[Yy]$ ]]; then
- REPO_DIR="$REPO_DIR" bash "$wt_script"
- else
- echo "Skipping Work Tracker installation."
- fi
- fi
- }
- # Main
- main() {
- if [ "$UPGRADE_MODE" -eq 1 ]; then
- print_upgrade_banner
- fi
- check_deps
- init_submodules
- backup
- link_files
- apply_cc_chips_custom
- validate_mcp_v3
- # v3.0 compat symlinks (upgrade mode only)
- if [ "$UPGRADE_MODE" -eq 1 ]; then
- echo ""
- echo "Creating v3.0 compat links..."
- create_v3_compat_links
- fi
- if [ "$DRY_RUN" -eq 1 ]; then
- echo ""
- echo -e "${YELLOW}[DRY-RUN] Skipping verify/metadata/MCP/skills/tracker steps.${NC}"
- if [ "$UPGRADE_MODE" -eq 1 ]; then
- print_upgrade_summary
- fi
- return 0
- fi
- if verify; then
- echo ""
- echo -e "${GREEN}Symlinks created successfully!${NC}"
- # Write forge metadata
- write_meta
- # Setup shell aliases
- setup_shell_aliases
- # Install MCP servers
- install_mcp_servers
- # Install external skills
- install_external_skills
- # Install work tracker
- install_work_tracker
- if [ "$UPGRADE_MODE" -eq 1 ]; then
- print_upgrade_summary
- fi
- echo ""
- cat << COMPLETE
- ${GREEN}╔══════════════════════════════════════════════════════╗
- ║ Claude Forge 설치 완료! ║
- ╠══════════════════════════════════════════════════════╣
- ║ 16 agents · 35 commands · 6-layer security ║
- ╚══════════════════════════════════════════════════════╝${NC}
- 처음이신가요? 이것만 하세요:
- 1. 새 터미널을 열고 'claude' 실행
- 2. ${GREEN}/guide${NC} 입력 — 3분 인터랙티브 가이드
- 자주 쓰는 TOP 5:
- /plan AI가 구현 계획을 세워줍니다
- /tdd 테스트 먼저 만들고 코드 작성
- /code-review 코드 보안+품질 검사
- /handoff-verify 빌드/테스트/린트 자동 검증
- /auto 계획부터 PR까지 원버튼 자동
- ${YELLOW}★ Star: github.com/sangrokjung/claude-forge${NC}
- ${YELLOW}? Issues: github.com/sangrokjung/claude-forge/issues${NC}
- COMPLETE
- else
- echo ""
- echo -e "${RED}Installation completed with errors${NC}"
- exit 1
- fi
- }
- main "$@"
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.