Skip to content
Back to search

claude-forge

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/sangrokjung-claude-forge/badge.svg)](/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)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "claude-forge",
  4. "version": "4.3.0",
  5. "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",
  6. "owner": {
  7. "name": "Sangrok Jung",
  8. "url": "https://github.com/sangrokjung"
  9. },
  10. "plugins": [
  11. {
  12. "name": "claude-forge",
  13. "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.",
  14. "version": "4.3.0",
  15. "author": {
  16. "name": "Sangrok Jung",
  17. "url": "https://github.com/sangrokjung"
  18. },
  19. "source": ".",
  20. "category": "development",
  21. "homepage": "https://github.com/sangrokjung/claude-forge",
  22. "tags": [
  23. "agents",
  24. "skills",
  25. "hooks",
  26. "tdd",
  27. "code-review",
  28. "security",
  29. "automation",
  30. "mcp-minimal",
  31. "mcp-chrome-devtools",
  32. "lighthouse",
  33. "performance",
  34. "adversarial-review"
  35. ]
  36. }
  37. ]
  38. }
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)

  1. <picture>
  2. <source media="(prefers-color-scheme: dark)" srcset="docs/banner.jpg">
  3. <source media="(prefers-color-scheme: light)" srcset="docs/banner-light.jpg">
  4. <img src="docs/banner.jpg" alt="Claude Forge" width="100%">
  5. </picture>
  6. <p align="center">
  7. <a href="https://sangrokjung.github.io/claude-forge/"><b>⚡ New here? Walk through setup in 60 seconds →</b></a>
  8. </p>
  9. <p align="center">
  10. <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>
  11. </p>
  12. <p align="center">
  13. <strong>oh-my-zsh for Claude Code — one install, full professional kit</strong>
  14. </p>
  15. <p align="center">
  16. <a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-blue?style=for-the-badge" alt="MIT License"></a>
  17. <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>
  18. <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>
  19. <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>
  20. <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>
  21. <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>
  22. </p>
  23. <p align="center">
  24. <a href="#what-is-claude-forge">What is it?</a> &bull;
  25. <a href="#-why-bother">Why bother?</a> &bull;
  26. <a href="#-install-in-minutes">Install</a> &bull;
  27. <a href="#-whats-inside">What's inside</a> &bull;
  28. <a href="#-how-to-use-it">How to use</a> &bull;
  29. <a href="#-architecture">Architecture</a> &bull;
  30. <a href="#-faq">FAQ</a> &bull;
  31. <a href="README.ko.md">한국어</a>
  32. </p>
  33. > **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)).
  34. >
  35. > **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.
  36. >
  37. > **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.
  38. >
  39. > **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).
  40. >
  41. > 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).
  42. > **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).
  43. ---
  44. ## What is Claude Forge?
  45. **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.
  46. Claude Forge is the **equipment pack** for that assistant. One install gives it:
  47. - 16 specialist "colleagues" (agents) it can delegate to — planner, security reviewer, TDD guide, adversarial reviewer, and more
  48. - 35 one-word shortcuts (commands like `/plan`, `/tdd`, `/code-review`) that trigger full workflows
  49. - 33 saved procedures (skills) it follows automatically
  50. - 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
  51. - 14 rule files that define how it should behave
  52. - 4 external tool connections (browser automation, live docs search, and more)
  53. > **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.
  54. ---
  55. ## ✨ Why bother?
  56. | Without Claude Forge | With Claude Forge |
  57. |:---------------------|:-----------------|
  58. | 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 |
  59. | No safety net — Claude can run dangerous commands or leak secrets by accident | 6-layer hook system blocks risky actions before they happen |
  60. | One AI doing everything alone | 16 specialist agents working in parallel (planner, architect, security reviewer, adversarial reviewer…) |
  61. | Hours assembling your own config | 5-minute install, everything pre-wired |
  62. | Updates require manual copy-paste | `git pull` — done |
  63. ---
  64. ## 📥 Install in Minutes
  65. ![Install in 3 steps](assets/readme/install-steps.png)
  66. ### Option A — Claude Code Plugin (quick start, partial features)
  67. Open a Claude Code session and run two commands:
  68. ```
  69. /plugin marketplace add sangrokjung/claude-forge
  70. /plugin install claude-forge
  71. ```
  72. This gets you commands and most skills right away. Agents, hooks, rules, and MCP connections need Option B.
  73. Update later: `/plugin update claude-forge`
  74. ### Option B — Full Install (recommended, everything included)
  75. One line in your terminal:
  76. ```bash
  77. 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
  78. ```
  79. Or if you prefer to clone first:
  80. ```bash
  81. git clone --recurse-submodules https://github.com/sangrokjung/claude-forge.git
  82. cd claude-forge
  83. ./install.sh # fresh install
  84. # or
  85. ./install.sh --upgrade # safe migration from v2.1
  86. ```
  87. **Windows users:** Run `.\install.ps1` in PowerShell as Administrator.
  88. ### Which option should I pick?
  89. | What you get | Option A (`/plugin install`) | Option B (`./install.sh`) |
  90. |:-------------|:----------------------------:|:-------------------------:|
  91. | Commands (35 shortcuts) | ✅ | ✅ |
  92. | Skills (33 saved procedures) | ⚠️ partial | ✅ |
  93. | Agents (16 specialists) | ❌ | ✅ |
  94. | Hooks (22 safety checks) | ❌ | ✅ |
  95. | Rules (14 behavior guidelines) | ❌ | ✅ |
  96. | MCP connections (4 tools) | ❌ | ✅ |
  97. **Recommendation:** Use Option B unless you only need a taste of commands and skills.
  98. > If Claude Forge helps you, a [star on GitHub](https://github.com/sangrokjung/claude-forge/stargazers) helps others find it.
  99. ---
  100. ## 📦 What's Inside
  101. ![What's inside](assets/readme/whats-inside.png)
  102. Here is everything bundled in Claude Forge, explained in plain language:
  103. | What | Count | Plain English |
  104. |:-----|:-----:|:--------------|
  105. | **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. |
  106. | **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. |
  107. | **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. |
  108. | **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. |
  109. | **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. |
  110. | **MCP connections** (external tools) | 4 | Browser automation (Playwright), live library docs (context7), web page reader (jina-reader), and Chrome DevTools for performance audits. |
  111. <details>
  112. <summary><strong>Full list: 16 Agents</strong></summary>
  113. #### Deep Analysis Agents (use the most capable model)
  114. | Agent | What it does |
  115. |:------|:-------------|
  116. | **planner** | Creates detailed implementation plans for complex features. Waits for your sign-off before any code is written. |
  117. | **architect** | Designs system structure, makes scalability decisions, reviews technical architecture. |
  118. | **code-reviewer** | Checks code quality, security, and maintainability after you write it. |
  119. | **security-reviewer** | Scans for OWASP Top 10 vulnerabilities, leaked secrets, injection risks. |
  120. | **tdd-guide** | Enforces test-first development: RED (failing test) → GREEN (passing) → IMPROVE (refactor). |
  121. | **database-reviewer** | Optimizes PostgreSQL/Supabase queries, reviews schema design. |
  122. #### Fast Execution Agents (use a quicker model)
  123. | Agent | What it does |
  124. |:------|:-------------|
  125. | **build-error-resolver** | Fixes TypeScript and build errors with minimal changes to surrounding code. |
  126. | **e2e-runner** | Generates and runs Playwright end-to-end browser tests. |
  127. | **refactor-cleaner** | Finds and removes dead code using knip, depcheck, ts-prune. |
  128. | **doc-updater** | Keeps documentation and code maps in sync after changes. |
  129. | **verify-agent** | Opens a fresh context to verify build, lint, and tests all pass — like a second pair of eyes. |
  130. #### Verification & Debugging Agents (v4.0)
  131. | Agent | What it does |
  132. |:------|:-------------|
  133. | **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`. |
  134. | **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. |
  135. | **systematic-debugger** | Reproduce → bisect → hypothesize → verify. Never guesses at a fix without a failing test that proves the hypothesis. |
  136. | **rca-debugger** | Escalation from systematic-debugger for multi-system failures — 5-why + fishbone analysis when bisection alone is inconclusive. |
  137. | **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. |
  138. </details>
  139. <details>
  140. <summary><strong>Full list: 35 Commands</strong></summary>
  141. #### Core Workflow
  142. | Command | What it does |
  143. |:--------|:------------|
  144. | `/plan` | AI creates an implementation plan. Waits for your confirmation before coding. |
  145. | `/tdd` | Write tests first, then code. One unit of work at a time. |
  146. | `/code-review` | Security + quality check on the code you just wrote. |
  147. | `/handoff-verify` | Auto-verify build/test/lint all at once. |
  148. | `/commit-push-pr` | Commit, push, create PR, and optionally merge — all in one. |
  149. | `/quick-commit` | Fast commit for simple, well-tested changes. |
  150. | `/verify-loop` | Auto-retry build/lint/test up to 3x with auto-fix. |
  151. | `/auto` | One-button automation: plan to PR without stopping. |
  152. | `/guide` | Interactive 3-minute tour for first-time users. |
  153. | `/loop-forge` | Turn a repetitive task into a reusable, self-guarding slash command. |
  154. | `/workflow-classify` | Size a task S/M/L/XL and route documentation depth + verification rigor accordingly. |
  155. #### Exploration & Analysis
  156. | Command | What it does |
  157. |:--------|:------------|
  158. | `/explore` | Navigate and analyze codebase structure. |
  159. | `/build-fix` | Incrementally fix TypeScript and build errors. |
  160. | `/next-task` | Recommend next task based on project state. |
  161. | `/suggest-automation` | Analyze repetitive patterns and suggest automation. |
  162. | `/agent-router` | Route a request to the specialist agent best suited for the task. |
  163. #### Security
  164. | Command | What it does |
  165. |:--------|:------------|
  166. | `/security-review` | CWE Top 25 + STRIDE threat modeling. |
  167. #### Testing & Evaluation
  168. | Command | What it does |
  169. |:--------|:------------|
  170. | `/e2e` | Generate and run Playwright end-to-end tests. |
  171. | `/test-coverage` | Analyze coverage gaps and generate missing tests. |
  172. | `/eval` | Eval-driven development workflow management. |
  173. #### Documentation & Sync
  174. | Command | What it does |
  175. |:--------|:------------|
  176. | `/update-codemaps` | Analyze codebase and update architecture docs. |
  177. | `/update-docs` | Sync documentation from source-of-truth. |
  178. | `/sync-docs` | Sync prompt_plan.md, spec.md, CLAUDE.md + rules. |
  179. | `/sync` | Pull latest changes and sync all project docs. Use after any workflow or at session start. |
  180. | `/pull` | Quick `git pull origin main`. |
  181. | `/forge-update` | Update Claude Forge itself to the latest version from the remote. |
  182. | `/show-setup` | Show the current install status and project info. |
  183. #### Project Management
  184. | Command | What it does |
  185. |:--------|:------------|
  186. | `/init-project` | Scaffold new project with standard structure. |
  187. | `/orchestrate` | Agent Teams parallel orchestration. |
  188. | `/checkpoint` | Save/restore work state. |
  189. | `/learn` | Record lessons learned + suggest automation. |
  190. | `/web-checklist` | Post-merge web testing checklist. |
  191. #### Refactoring & Debugging
  192. | Command | What it does |
  193. |:--------|:------------|
  194. | `/refactor-clean` | Identify and remove dead code with test verification. |
  195. #### Git Worktree
  196. | Command | What it does |
  197. |:--------|:------------|
  198. | `/worktree-start` | Create git worktree for parallel development. |
  199. | `/worktree-cleanup` | Clean up worktrees after PR completion. |
  200. </details>
  201. > The 8 commands that moved to `skills/` in v3.0 (`debugging-strategies`, `dependency-upgrade`,
  202. > `evaluating-code-models`, `evaluating-llms-harness`, `extract-errors`, `security-compliance`,
  203. > `stride-analysis-patterns`, `summarize`) are listed once, under Skills below — see
  204. > [MIGRATION.md](MIGRATION.md) Step 5. `install.sh` still creates compatibility symlinks under
  205. > `commands/` for them.
  206. <details>
  207. <summary><strong>Full list: 33 Skills</strong></summary>
  208. | Skill | What it does |
  209. |:------|:------------|
  210. | **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. |
  211. | **build-system** | Auto-detect and run project build systems. |
  212. | **cache-components** | Next.js Cache Components and Partial Prerendering (PPR) guidance. |
  213. | **cc-dev-agent** | Claude Code development workflow optimization (context engineering, sub-agents, TDD). |
  214. | **continuous-learning-v2** | Instinct-based learning: observe sessions via hooks, create atomic instincts with confidence scoring. |
  215. | **debugging-strategies** | Systematic debugging techniques and profiling. |
  216. | **dependency-upgrade** | Major dependency upgrades with compatibility analysis. |
  217. | **eval-harness** | Formal evaluation framework for eval-driven development (EDD). |
  218. | **evaluating-code-models** | Benchmark code generation models (HumanEval, MBPP). |
  219. | **evaluating-llms-harness** | Benchmark LLMs across 60+ academic benchmarks. |
  220. | **extract-errors** | Extract and catalog error messages. |
  221. | **frontend-code-review** | Frontend file review (.tsx, .ts, .js) with checklist rules. |
  222. | **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. |
  223. | **humanize-korean** | Strip translation-ese and AI idioms from Korean prose without changing facts, numbers, or register. |
  224. | **korean-character-count** | Count Korean characters/syllables for length-constrained copy (titles, SMS, ad copy). |
  225. | **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. |
  226. | **loop-forge** | Turn a one-line repetitive task into a reusable, self-guarding slash command (5 loop shapes + auto verifier & hardstop). |
  227. | **manage-skills** | Analyze session changes, detect missing verification skills, create/update skills. |
  228. | **prompts-chat** | Skill/prompt exploration, search, and improvement. |
  229. | **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. |
  230. | **review-loop** | The adversarial verification loop procedure: dispatch `adversarial-reviewer`, act on `REQUEST_CHANGES`, stop only on `APPROVE` against the current revision. |
  231. | **security-compliance** | SOC2, ISO27001, GDPR, HIPAA compliance checks. |
  232. | **security-pipeline** | CWE Top 25 + STRIDE automated security verification pipeline. |
  233. | **session-wrap** | End-of-session cleanup: 4 parallel subagents detect docs, patterns, learnings, follow-ups. |
  234. | **skill-factory** | Convert reusable session patterns into Claude Code skills automatically. |
  235. | **strategic-compact** | Suggest manual context compaction at logical intervals to preserve context. |
  236. | **stride-analysis-patterns** | Systematic STRIDE methodology for threat identification. |
  237. | **summarize** | Summarize URLs, podcasts, transcripts, local files. |
  238. | **systematic-debugging** | 6-phase structured debugging procedure — reproduce, isolate, hypothesize, test, fix, verify. |
  239. | **team-orchestrator** | Agent Teams engine: team composition, task distribution, dependency management. |
  240. | **using-superpowers** | Discover and invoke installed skills before responding to any request. |
  241. | **verification-engine** | Integrated verification engine: fresh-context subagent verification loop. |
  242. | **verify-implementation** | Run all project verify skills and generate unified pattern verification report. |
  243. </details>
  244. <details>
  245. <summary><strong>Full list: 22 Hooks (safety checks)</strong></summary>
  246. #### Security Hooks — block dangerous actions automatically
  247. <p align="center">
  248. <img src="docs/security-layers.jpg" alt="6-Layer Security Defense" width="480">
  249. </p>
  250. | Hook | When it runs | What it blocks |
  251. |:-----|:------------|:---------------|
  252. | `output-secret-filter.sh` | After every tool use | Leaked API keys, tokens, passwords in output |
  253. | `remote-command-guard.sh` | Before Bash commands | Unsafe remote commands (curl pipe, wget pipe) |
  254. | `db-guard.sh` | Before database commands | Destructive SQL (DROP, TRUNCATE, DELETE without WHERE) |
  255. | `security-auto-trigger.sh` | After file edits | Vulnerabilities in code changes |
  256. | `rate-limiter.sh` | Before MCP tool use | MCP server abuse / excessive calls |
  257. | `mcp-usage-tracker.sh` | Before MCP tool use | Tracks MCP usage for monitoring |
  258. #### Reliability Hooks — v4.0, unattended-session safety net
  259. | Hook | When it runs | What it does |
  260. |:-----|:------------|:-------------|
  261. | `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) |
  262. | `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) |
  263. | `auto-verify-fix.sh` | After editing a `.ts`/`.tsx`/`.js`/`.jsx`/`.py` file | Lightweight type/syntax check, surfaces fixable errors immediately |
  264. | `pre-compact-snapshot.sh` | Before context compaction (`PreCompact`) | Snapshots the pointer to the most recent `relay` skill baton |
  265. | `post-compact-restore.sh` | Right after `/compact` (`SessionStart`, matcher `compact`) | Restores that pointer into the fresh session's context, exactly once |
  266. | `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) |
  267. #### Utility Hooks — helpful nudges in the background
  268. | Hook | When it runs | What it does |
  269. |:-----|:------------|:-------------|
  270. | `code-quality-reminder.sh` | After file edits | Reminds about immutability, small files, error handling |
  271. | `context-sync-suggest.sh` | Session start | Suggests syncing docs at session start |
  272. | `forge-update-check.sh` | Session start | Tells you when a newer claude-forge release is available |
  273. | `session-wrap-suggest.sh` | Before session end | Suggests session wrap-up before ending |
  274. | `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) |
  275. | `work-tracker-prompt.sh` | When you submit a prompt | Tracks work for analytics |
  276. | `work-tracker-tool.sh` | After tool use | Tracks tool usage for analytics |
  277. | `work-tracker-stop.sh` | On stop | Finalizes work tracking data |
  278. | `task-completed.sh` | When subagent finishes | Notifies on subagent task completion |
  279. | `expensive-mcp-warning.sh` | Before costly operations | Warns about expensive MCP calls |
  280. An opt-in **pre-commit secret guard** (`scripts/install-precommit.sh`) also ships as of v4.0
  281. — it protects git commits in any repo you point it at, separately from the hooks above.
  282. See [`docs/RELIABILITY.md`](docs/RELIABILITY.md).
  283. #### End-of-session report
  284. `session-time-report.sh` measures a session as it closes and hands you the summary the next time you open one:
  285. ```
  286. [Claude Forge] Previous session ended 21:34 KST
  287. 2h 17m elapsed · 18 prompts · 143 tool calls · 9 files changed
  288. Log: ~/.claude/work-log/session-time-<session_id>.json
  289. ```
  290. **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.
  291. It reads only the session transcript, so there is no network call and no extra dependency beyond `python3`.
  292. **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.
  293. **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)`.
  294. | Environment variable | Default | Effect |
  295. |:---------------------|:--------|:-------|
  296. | `FORGE_SESSION_TIME_REPORT` | `1` | Set to `0` to turn the hook off |
  297. | `FORGE_SESSION_GAP_MIN` | `60` | Idle minutes that start a new stretch |
  298. | `FORGE_SESSION_MAX_MB` | `128` | Transcript megabytes to scan, up to 512; larger files are read from the tail |
  299. | `FORGE_SESSION_MAX_SEC` | `4` | Wall-clock budget for the scan. Past it the report is dropped rather than reported half-read |
  300. | `FORGE_SESSION_REPORT_LANG` | auto | `en` or `ko`; auto-detects from `LANG` / `LC_ALL` |
  301. 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.
  302. #### Opt-in Examples (9 extra, v3.0+)
  303. 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`.
  304. </details>
  305. ---
  306. ## 🔄 How to Use It
  307. ![Development workflow](assets/readme/workflow.png)
  308. ### The main development pipeline
  309. Claude Forge's commands are designed to chain together. Here is the recommended flow for building any new feature:
  310. ```
  311. /plan → /tdd → /code-review → /handoff-verify → /commit-push-pr
  312. ```
  313. <p align="center">
  314. <img src="docs/workflow-pipeline.jpg" alt="Feature Development Workflow" width="720">
  315. </p>
  316. | Step | What Claude does | Why |
  317. |:-----|:-----------------|:----|
  318. | `/plan` | Writes an implementation plan and waits for your go-ahead | No code is written until you approve the approach |
  319. | `/tdd` | Writes the tests first, then writes the code to pass them | Catches mistakes before they become bugs |
  320. | `/code-review` | Checks the finished code for security holes and quality issues | A second pair of eyes, automatically |
  321. | `/handoff-verify` | Runs build, tests, and lint in a fresh session to confirm everything passes | Catches "works on my machine" problems |
  322. | `/commit-push-pr` | Commits the code, pushes to GitHub, creates a pull request, and optionally merges it | One command to ship |
  323. ### Other common workflows
  324. **Fixing a bug:**
  325. ```
  326. /explore → /tdd → /verify-loop → /quick-commit → /sync
  327. ```
  328. **Security audit:**
  329. ```
  330. /security-review → /stride-analysis-patterns → /security-compliance
  331. ```
  332. **Parallel team work (multiple agents at once):**
  333. ```
  334. /orchestrate → Agent Teams (working in parallel) → /commit-push-pr
  335. ```
  336. <p align="center">
  337. <img src="docs/agent-teams.jpg" alt="Agent Teams Hub-and-Spoke" width="600">
  338. </p>
  339. ### Not sure where to start?
  340. After installing, type `/guide` for an interactive 3-minute tour. Or just type:
  341. ```
  342. /auto login page
  343. ```
  344. Claude Forge will handle the entire plan-to-PR pipeline for you automatically.
  345. Prefer to read first? [`docs/FIRST-STEPS.md`](docs/FIRST-STEPS.md) walks through your first
  346. session step by step, and [`docs/WORKFLOW-RECIPES.md`](docs/WORKFLOW-RECIPES.md) collects the
  347. command sequences for common jobs.
  348. ---
  349. ## 🏗 Architecture
  350. <p align="center">
  351. <img src="docs/architecture.jpg" alt="Symlink Architecture" width="720">
  352. </p>
  353. 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.
  354. ```mermaid
  355. graph LR
  356. REPO["claude-forge repo<br>(git pull to update)"]
  357. INSTALL["./install.sh<br>(one-time setup)"]
  358. HOME["~/.claude/<br>(Claude reads this)"]
  359. CLAUDE["Claude Code"]
  360. REPO --> INSTALL
  361. INSTALL -->|"creates symlinks"| HOME
  362. HOME --> CLAUDE
  363. ```
  364. > **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).
  365. <details>
  366. <summary><strong>Full Directory Tree</strong></summary>
  367. ```
  368. claude-forge/
  369. ├── agents/ Agent definitions (16 .md files, frontmatter v2)
  370. ├── cc-chips/ Status bar submodule
  371. ├── cc-chips-custom/ Custom status bar overlay
  372. ├── commands/ Slash commands (35 .md, 8 dirs moved to skills/)
  373. ├── docs/ Screenshots, diagrams, policy docs (v3.0+ guides, incl. RELIABILITY.md / VERIFICATION-LOOP.md)
  374. ├── hooks/ Event-driven shell scripts (22)
  375. │ └── examples/ Opt-in .example samples for 21 lifecycle events (9)
  376. ├── knowledge/ Knowledge base entries
  377. ├── libs/ Shared shell libraries hooks source (hook-guard.sh)
  378. ├── reference/ Reference docs (+ agent-schema.json, ai-tell-taxonomy.md)
  379. ├── rules/ Auto-loaded rule files (14)
  380. ├── scripts/ Utility scripts (incl. install-precommit.sh, api-error-resume-runner.sh)
  381. ├── setup/ Installation guides + CLAUDE.md template
  382. ├── skills/ Multi-step skill workflows (33, hybrid policy)
  383. ├── install.sh macOS/Linux installer (--upgrade supported)
  384. ├── install.ps1 Windows installer (--upgrade supported)
  385. ├── mcp-servers.json MCP server defaults (4 minimal)
  386. ├── mcp-servers.optional.json Optional MCP servers (memory/exa/github/fetch/time/...)
  387. ├── .claude-plugin/plugin.json Plugin manifest (4.3.0)
  388. ├── .claude-plugin/marketplace.json Marketplace entry (4.3.0)
  389. ├── settings.json Claude Code settings (2026 fields)
  390. ├── MIGRATION.md v2.1 → v4.0 migration guide (EN)
  391. ├── MIGRATION.ko.md v2.1 → v4.0 migration guide (KO)
  392. ├── CONTRIBUTING.md Contribution guide
  393. ├── SECURITY.md Security policy
  394. └── LICENSE MIT License
  395. ```
  396. </details>
  397. ---
  398. ## 🔧 What's New in v4.0
  399. <details open>
  400. <summary><strong>v4.0 changes (click to collapse)</strong></summary>
  401. | Change | Description |
  402. |:-------|:------------|
  403. | **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). |
  404. | **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). |
  405. | **Debugging escalation chain** | `systematic-debugger` → `rca-debugger` → `escalation-fixer`. Each step only fires when the one before it couldn't close the case. |
  406. | **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`). |
  407. | **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. |
  408. Inventory: 11 → **16 agents**, 34 → **35 commands**, 26 → **32 skills**, 15 → **21 hooks**,
  409. 10 → **14 rules**. See [MIGRATION.md](MIGRATION.md) for the full v3 → v4 upgrade guide.
  410. </details>
  411. ## 🔧 What's New in v3.0 (historical)
  412. <details>
  413. <summary><strong>v3.0 → v3.1.0 changes (click to expand)</strong></summary>
  414. ### v3.1.0 (feature, June 2026)
  415. - **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.
  416. - **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.
  417. ### v3.0.2 (docs patch, May 2026)
  418. 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).
  419. ### v3.0.1 (patch)
  420. | Change | Description |
  421. |:-------|:------------|
  422. | **Plugin Manifest shipped** | `/plugin marketplace add sangrokjung/claude-forge` + `/plugin install claude-forge` now work for Commands + Skills. |
  423. | **Chrome DevTools promoted** | Lighthouse / Core Web Vitals / memory snapshots now in the default 4-server set. Pinned at `chrome-devtools-mcp@0.23.0`. |
  424. | **`hooks/_lib/timing.sh`** | Records SessionEnd hook timing into `~/.claude/logs/hook-timing.jsonl`. |
  425. | **CI expanded** | Runs on every PR and on `main`/`feat/**`/`fix/**`/`chore/**`/`docs/**`/`ci/**` pushes. 6 jobs total. |
  426. | **Tier 0 spec corrections** | Hook types, timeout units, Auto Memory path all corrected. |
  427. | **New governance docs** | ADR-001, SETTINGS-COMPATIBILITY, MARKETPLACE-SUBMISSION. |
  428. ### v3.0 (major)
  429. | Change | Description |
  430. |:-------|:------------|
  431. | **Hooks 21 Events** | Lifecycle hooks expanded from 5 to 21 events. Opt-in samples in [`hooks/examples/`](hooks/examples/). |
  432. | **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). |
  433. | **Skills/Commands Hybrid Policy** | Clear boundary documented at [`docs/SKILLS-VS-COMMANDS.md`](docs/SKILLS-VS-COMMANDS.md). |
  434. | **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). |
  435. | **CLAUDE.md Template** | New [`setup/CLAUDE.md.template`](setup/CLAUDE.md.template) with `@import` pattern. |
  436. | **Upgrade in One Command** | `./install.sh --upgrade` safely migrates v2.1 installs with backup and diff preview. |
  437. ### Breaking Changes in v3.0
  438. - **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.
  439. - **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`.
  440. - **settings.json allowlist** — Removed `mcp__memory`, `mcp__exa`, `mcp__github`, `mcp__fetch`. Added `mcp__playwright`.
  441. </details>
  442. ---
  443. ## 🛠 MCP Servers (External Tool Connections)
  444. | Server | What it does | Required setup |
  445. |:-------|:------------|:---------------|
  446. | **playwright** | Controls a real browser for end-to-end tests | None — auto-installed |
  447. | **context7** | Fetches live library documentation while coding | None — auto-installed |
  448. | **jina-reader** | Reads web pages and converts them to clean text | None — auto-installed |
  449. | **chrome-devtools** | Runs Lighthouse audits and Core Web Vitals checks | None — auto-installed |
  450. 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).
  451. ---
  452. ## ⚙️ Customization
  453. Override any setting without modifying tracked files:
  454. ```bash
  455. cp setup/settings.local.template.json ~/.claude/settings.local.json
  456. # Edit ~/.claude/settings.local.json with your preferences
  457. ```
  458. `settings.local.json` merges on top of `settings.json` automatically — your changes survive `git pull`.
  459. ---
  460. ## 🆚 Claude Forge vs. Starting From Scratch
  461. | Feature | Claude Forge | Basic `.claude/` setup | Individual plugins |
  462. |:--------|:-----------:|:----------------------:|:------------------:|
  463. | Specialist agents | 16 ready | Manual setup | Varies |
  464. | Slash commands | 35 ready | None | Per-plugin |
  465. | Skill workflows | 33 ready | None | Per-plugin |
  466. | Safety hooks | 22 + 9 examples | None by default | Per-plugin |
  467. | External tool connections | 4 default (8+ optional) | None | Per-plugin |
  468. | Setup time | ~5 minutes | Hours | Per-plugin install |
  469. | Updates | `git pull` | Manual per-file | Per-plugin update |
  470. | End-to-end pipeline | Plan → Test → Review → Ship | Disconnected tools | Not integrated |
  471. ---
  472. ## ❓ FAQ
  473. <details>
  474. <summary><strong>Do I need to know how to code to use Claude Forge?</strong></summary>
  475. 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.
  476. If you are new, start with `/guide` after installing. It gives you an interactive 3-minute tour.
  477. </details>
  478. <details>
  479. <summary><strong>What is Claude Code?</strong></summary>
  480. 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.
  481. </details>
  482. <details>
  483. <summary><strong>How is Claude Forge different from other Claude Code plugins?</strong></summary>
  484. 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.
  485. </details>
  486. <details>
  487. <summary><strong>Is Claude Forge compatible with the official Claude Code plugin system?</strong></summary>
  488. 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.
  489. </details>
  490. <details>
  491. <summary><strong>How do I update Claude Forge?</strong></summary>
  492. 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.
  493. </details>
  494. <details>
  495. <summary><strong>Does Claude Forge work on Windows?</strong></summary>
  496. 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.
  497. </details>
  498. <details>
  499. <summary><strong>What does /sync do?</strong></summary>
  500. `/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.
  501. </details>
  502. <details>
  503. <summary><strong>How does Claude Forge handle memory across sessions?</strong></summary>
  504. Claude Forge uses a 4-layer memory system:
  505. 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.
  506. 2. **Rule files** (`rules/`) — Coding style, security, and workflow conventions loaded automatically each session.
  507. 3. **MCP memory server** — A persistent knowledge graph that stores entities and relations across sessions (opt-in).
  508. 4. **Agent memory** (`~/.claude/agent-memory/`) — Core agents record learnings after each task, improving their recommendations over time.
  509. Running `/sync` at session start ensures layers 1 and 2 are current.
  510. </details>
  511. ---
  512. ## 🤝 Contributing
  513. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding agents, commands, skills, and hooks.
  514. ---
  515. ## Use Claude Forge? Show it!
  516. ```markdown
  517. [![Built with Claude Forge](https://img.shields.io/badge/Built_with-Claude_Forge-orange?style=flat-square)](https://github.com/sangrokjung/claude-forge)
  518. ```
  519. Add this badge to your project's README to let others know you use Claude Forge.
  520. ---
  521. ## ⭐ Star History
  522. [![Star History Chart](https://api.star-history.com/svg?repos=sangrokjung/claude-forge&type=Date)](https://www.star-history.com/#sangrokjung/claude-forge&Date)
  523. ---
  524. ## Contributors
  525. <a href="https://github.com/sangrokjung/claude-forge/graphs/contributors">
  526. <img src="https://contrib.rocks/image?repo=sangrokjung/claude-forge" />
  527. </a>
  528. ---
  529. ## 📄 License
  530. [MIT](LICENSE) — use it, fork it, build on it.
  531. If Claude Forge improved your workflow, a [star](https://github.com/sangrokjung/claude-forge/stargazers) helps others find it too.
  532. ---
  533. <p align="center">
  534. <sub>Made with ❤️ by <a href="https://github.com/sangrokjung">QJC (Quantum Jump Club)</a></sub>
  535. </p>
.claude-plugin/plugin.json · Bundled script · 33 lines · 1 finding marked
  1. {
  2. "name": "claude-forge",
  3. "version": "4.3.0",
  4. "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
  5. "author": {
  6. "name": "Sangrok Jung",
  7. "url": "https://github.com/sangrokjung"
  8. },
  9. "repository": "https://github.com/sangrokjung/claude-forge",
  10. "homepage": "https://github.com/sangrokjung/claude-forge",
  11. "license": "MIT",
  12. "keywords": [
  13. "claude-code",
  14. "development-environment",
  15. "agents",
  16. "skills",
  17. "hooks",
  18. "tdd",
  19. "code-review",
  20. "security",
  21. "automation",
  22. "oh-my-zsh",
  23. "hooks-22",
  24. "skills-commands-hybrid",
  25. "mcp-minimal",
  26. "adversarial-review",
  27. "v4"
  28. ],
  29. "engines": {
  30. "claude-code": ">=2.1.110"
  31. },
  32. "minClaudeCodeVersion": "2.1.110"
  33. }
hooks/remote-command-guard.sh · Bundled script · 213 lines · 1 finding marked
  1. #!/bin/bash
  2. # Remote Command Guard - PreToolUse Hook
  3. # 원격 Claude Code 세션에서 위험한 Bash 명령을 차단
  4. #
  5. # Hook trigger: PreToolUse, matcher: Bash
  6. # Exit codes: 0 = 허용, 2 = 차단
  7. #
  8. # 차단 범주:
  9. # 1. 파괴적 삭제 (rm -rf /, rm -rf ~, rm -rf *)
  10. # 2. 환경변수/시크릿 유출 (env, printenv, echo $SECRET 등)
  11. # 3. 경로 순회 (/etc/passwd, /etc/shadow 등)
  12. # 4. 외부 통신 (curl, wget, nc, ncat 등)
  13. # 5. 권한 변경 (chmod 777, chown, mount 등)
  14. # 6. 프로세스 종료 (kill -9, pkill 등)
  15. # 7. 명령 주입 (eval, exec 등)
  16. # 원격 세션이 아니면 검사 건너뜀
  17. if [[ -z "${OPENCLAW_SESSION_ID:-}" ]]; then
  18. exit 0
  19. fi
  20. # stdin에서 JSON 읽기
  21. INPUT=$(cat)
  22. # 명령어 추출 (python3 -c + 작은따옴표로 셸 확장 방지)
  23. COMMAND=$(echo "$INPUT" | python3 -c '
  24. import sys, json
  25. data = json.load(sys.stdin)
  26. print(data.get("tool_input", {}).get("command", ""))
  27. ' 2>/dev/null)
  28. if [[ -z "$COMMAND" ]]; then
  29. exit 0
  30. fi
  31. # 환경변수로 명령어 전달 → heredoc으로 Python 검사 로직 주입
  32. export _GUARD_CMD="$COMMAND"
  33. python3 << 'GUARD_SCRIPT'
  34. import os
  35. import sys
  36. import re
  37. command = os.environ.get("_GUARD_CMD", "")
  38. if not command:
  39. sys.exit(0)
  40. # 명령어 정규화 (여러 공백 → 단일 공백)
  41. cmd = re.sub(r'\s+', ' ', command.strip())
  42. cmd_lower = cmd.lower()
  43. blocked_reason = None
  44. # === 1. 파괴적 삭제 ===
  45. # rm -rf / , rm -rf ~ , rm -rf * 등 광범위 삭제만 차단
    • Dismissed after review: Runs `rm -rf` against a root or home-directory path
    • Line 54 on GitHub
  46. # rm /tmp/specific-file.txt 같은 특정 파일 삭제는 허용
  47. destructive_patterns = [
  48. r'\brm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s', # rm -rf, rm -rfi 등
  49. r'\brm\s+-[a-zA-Z]*f[a-zA-Z]*r[a-zA-Z]*\s', # rm -fr, rm -fri 등
  50. r'\brm\b.*\s+/$', # rm / (루트)
  51. r'\brm\b.*\s+/\s', # rm / something
  52. r'\brm\b.*\s+~/?(\s|$)', # rm ~ 또는 rm ~/
  53. r'\brm\b.*\s+\*(\s|$)', # rm * (현재 디렉토리 전체)
  54. r'\bmkfs\b',
  55. r'\bdd\s+.*of=/dev/',
  56. r'\b:\s*\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;',
  57. ]
  58. for pat in destructive_patterns:
  59. if re.search(pat, cmd_lower):
  60. blocked_reason = "파괴적 삭제 명령 감지"
  61. break
  62. # === 2. 환경변수/시크릿 유출 ===
  63. # 시크릿 패턴은 원본 cmd에 re.IGNORECASE로 매칭 (환경변수명 대소문자 보존)
  64. if not blocked_reason:
  65. secret_patterns = [
  66. r'\b(env|printenv|set)\s*$',
  67. r'\b(env|printenv|set)\s*\|',
  68. r'\becho\s+.*\$[A-Z_]*KEY\b',
  69. r'\becho\s+.*\$[A-Z_]*SECRET\b',
  70. r'\becho\s+.*\$[A-Z_]*TOKEN\b',
  71. r'\becho\s+.*\$[A-Z_]*PASSWORD\b',
  72. r'\becho\s+.*\$[A-Z_]*PASSWD\b',
  73. r'\becho\s+.*\$[A-Z_]*API\b',
  74. r'\becho\s+.*\$[A-Z_]*CREDENTIAL\b',
  75. r'\becho\s+.*\$(AWS_|OPENAI_|ANTHROPIC_|TELEGRAM_|GITHUB_|SUPABASE_)',
  76. r'\bcat\s+.*\.env\b',
  77. r'\bcat\s+.*\.netrc\b',
  78. r'\bcat\s+.*credentials\b',
  79. r'\bcat\s+.*/\.ssh/',
  80. r'\bexport\s+-p\s*$',
  81. r'\bexport\s+-p\s*\|',
  82. r'\bcat\s+.*seed\.txt\b',
  83. r'\bcat\s+.*wallet\.json\b',
  84. r'\bcat\s+.*keystore\b',
  85. ]
  86. for pat in secret_patterns:
  87. if re.search(pat, cmd, re.IGNORECASE):
  88. blocked_reason = "시크릿/환경변수 유출 시도 감지"
  89. break
  90. # === 3. 경로 순회 ===
  91. if not blocked_reason:
  92. path_traversal_patterns = [
  93. r'/etc/passwd',
  94. r'/etc/shadow',
  95. r'/etc/sudoers',
  96. r'/etc/master\.passwd',
  97. r'\.\./(\.\./)*(etc|proc|sys|dev)/',
  98. r'/proc/self/',
  99. r'/proc/\d+/',
  100. r'/sys/class/',
  101. ]
  102. for pat in path_traversal_patterns:
  103. if re.search(pat, cmd_lower):
  104. blocked_reason = "민감 시스템 경로 접근 감지"
  105. break
  106. # === 4. 외부 통신 ===
  107. if not blocked_reason:
  108. network_patterns = [
  109. r'\bcurl\s',
  110. r'\bwget\s',
  111. r'\bnc\s',
  112. r'\bncat\s',
  113. r'\bnetcat\s',
  114. r'\btelnet\s',
  115. r'\bssh\s',
  116. r'\bscp\s',
  117. r'\brsync\s.*:',
  118. r'\bftp\s',
  119. r'\bsftp\s',
  120. r'\bsocat\s',
  121. r'\bpython3?\s+-m\s+http\.server',
  122. r'\bphp\s+-S\s',
  123. r'\bnpm\s+publish\b',
  124. r'\bnpx\s.*ngrok',
  125. ]
  126. # localhost/127.0.0.1 대상 curl/wget은 허용 (개발용)
  127. is_local = bool(re.search(
  128. r'\bcurl\s+.*\b(localhost|127\.0\.0\.1|0\.0\.0\.0)\b', cmd_lower
  129. ))
  130. if not is_local:
  131. for pat in network_patterns:
  132. if re.search(pat, cmd_lower):
  133. blocked_reason = "외부 네트워크 통신 시도 감지"
  134. break
  135. # === 5. 권한 변경 ===
  136. if not blocked_reason:
  137. permission_patterns = [
  138. r'\bchmod\s+777\b',
  139. r'\bchmod\s+666\b',
  140. r'\bchmod\s+[0-7]*[67][0-7]{2}\b.*/(etc|usr|var|sys)',
  141. r'\bchown\s',
  142. r'\bmount\s',
  143. r'\bumount\s',
  144. r'\bsudo\s',
  145. r'\bsu\s+-?\s',
  146. r'\bdscl\s',
  147. ]
  148. for pat in permission_patterns:
  149. if re.search(pat, cmd_lower):
  150. blocked_reason = "권한 변경 명령 감지"
  151. break
  152. # === 6. 프로세스 종료 ===
  153. if not blocked_reason:
  154. process_patterns = [
  155. r'\bkill\s+-9\b',
  156. r'\bkill\s+-KILL\b',
  157. r'\bkill\s+-SIGKILL\b',
  158. r'\bkillall\s',
  159. r'\bpkill\s',
  160. r'\bxkill\b',
  161. r'\bshutdown\b',
  162. r'\breboot\b',
  163. r'\bhalt\b',
  164. r'\binit\s+[06]\b',
  165. ]
  166. for pat in process_patterns:
  167. if re.search(pat, cmd_lower):
  168. blocked_reason = "프로세스 종료/시스템 제어 명령 감지"
  169. break
  170. # === 7. 명령 주입 ===
  171. if not blocked_reason:
  172. injection_patterns = [
  173. r'\beval\s',
  174. r'\bexec\s',
  175. r'\bsource\s+/dev/',
  176. r'\bbash\s+-c\s.*\$\(',
  177. r'\bsh\s+-c\s.*\$\(',
  178. r'`[^`]*\$\([^)]+\)[^`]*`',
  179. r'\|\s*sh\b',
  180. r'\|\s*bash\b',
  181. r'\|\s*zsh\b',
  182. r'>\s*/dev/sd[a-z]',
  183. r'>\s*/dev/nvme',
  184. r'\bbase64\s+-d\s*\|\s*(sh|bash|zsh)',
  185. ]
  186. for pat in injection_patterns:
  187. if re.search(pat, cmd_lower):
  188. blocked_reason = "명령 주입 패턴 감지"
  189. break
  190. if blocked_reason:
  191. safe_cmd = cmd[:200]
  192. print(f"BLOCKED: {blocked_reason}", file=sys.stderr)
  193. print(f"Command: {safe_cmd}", file=sys.stderr)
  194. sys.exit(2)
  195. sys.exit(0)
  196. GUARD_SCRIPT
install.sh · Bundled script · 754 lines · 1 finding marked
  1. #!/bin/bash
  2. set -e
  3. REPO_DIR="$(cd "$(dirname "$0")" && pwd)"
  4. CLAUDE_DIR="$HOME/.claude"
  5. # Defaults
  6. UPGRADE_MODE=0
  7. DRY_RUN=0
  8. # Usage banner
  9. print_usage_and_exit() {
  10. cat << USAGE
  11. Usage: install.sh [OPTIONS]
  12. Options:
  13. --upgrade Upgrade existing installation to v4.0 (preserves symlinks,
  14. refreshes targets, prints breaking-change guidance).
  15. --dry-run Show what would change without modifying files.
  16. -h, --help Show this help message.
  17. Examples:
  18. ./install.sh # Fresh install
  19. ./install.sh --upgrade # Upgrade v2.x -> v4.0 in place
  20. ./install.sh --dry-run # Preview changes
  21. ./install.sh --upgrade --dry-run
  22. Breaking changes since v2.1, introduced in v3.0 (see MIGRATION.md):
  23. - MCP servers: 6 -> 3 (playwright, context7, jina-reader)
  24. - Hooks: 5 events -> 21 (opt-in via hooks/examples/)
  25. - Subagent frontmatter: v2 optional fields
  26. - Skills/Commands: hybrid policy (docs/SKILLS-VS-COMMANDS.md)
  27. USAGE
  28. exit 0
  29. }
  30. # Parse arguments
  31. while [ $# -gt 0 ]; do
  32. case "${1:-}" in
  33. --upgrade)
  34. UPGRADE_MODE=1
  35. shift
  36. ;;
  37. --dry-run)
  38. DRY_RUN=1
  39. shift
  40. ;;
  41. -h|--help)
  42. print_usage_and_exit
  43. ;;
  44. *)
  45. echo "Unknown option: $1" >&2
  46. echo "Run './install.sh --help' for usage." >&2
  47. exit 1
  48. ;;
  49. esac
  50. done
  51. # Detect platform
  52. detect_platform() {
  53. if [[ "$OSTYPE" == "darwin"* ]]; then
  54. PLATFORM="macos"
  55. ARCH="$(uname -m)"
  56. elif grep -qEi "(Microsoft|WSL)" /proc/version 2>/dev/null || [ -f /proc/sys/fs/binfmt_misc/WSLInterop ]; then
  57. PLATFORM="wsl"
  58. ARCH="$(uname -m)"
  59. elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
  60. PLATFORM="linux"
  61. ARCH="$(uname -m)"
  62. else
  63. PLATFORM="unknown"
  64. ARCH="$(uname -m)"
  65. fi
  66. }
  67. detect_platform
  68. cat << 'BANNER'
  69. ╔═╗┬ ┌─┐┬ ┬┌┬┐┌─┐ ╔═╗┌─┐┬─┐┌─┐┌─┐
  70. ║ │ ├─┤│ │ ││├┤ ╠╣ │ │├┬┘│ ┬├┤
  71. ╚═╝┴─┘┴ ┴└─┘─┴┘└─┘ ╚ └─┘┴└─└─┘└─┘
  72. Production-grade Claude Code Framework
  73. github.com/sangrokjung/claude-forge
  74. BANNER
  75. echo "Platform: $PLATFORM ($ARCH)"
  76. echo ""
  77. # Colors
  78. RED='\033[0;31m'
  79. GREEN='\033[0;32m'
  80. YELLOW='\033[1;33m'
  81. NC='\033[0m' # No Color
  82. # Upgrade banner (printed when --upgrade is set)
  83. print_upgrade_banner() {
  84. echo "=========================================="
  85. echo " claude-forge v4.0 Upgrade"
  86. echo "=========================================="
  87. echo ""
  88. echo " Breaking changes since v2.1:"
  89. echo " - MCP: 6 servers -> 3 (playwright, context7, jina-reader)"
  90. echo " - Removed: memory, exa, github, fetch"
  91. echo " - Recipes: docs/MCP-MIGRATION.md"
  92. echo " - Hooks: 5 events -> 21 (opt-in via hooks/examples/)"
  93. echo " - Subagent frontmatter: v2 optional fields"
  94. echo " - Skills/Commands: hybrid policy (docs/SKILLS-VS-COMMANDS.md)"
  95. echo ""
  96. if [ "$DRY_RUN" -eq 1 ]; then
  97. echo -e " ${YELLOW}[DRY-RUN] No files will be modified.${NC}"
  98. echo ""
  99. fi
  100. }
  101. # v3.0 skills/commands 호환 링크 (v2.1에서 commands로 제공되던 항목 일부가
  102. # v3.0에서 skills로 이동한 경우에 대한 하위 호환)
  103. create_v3_compat_links() {
  104. local target_base="$CLAUDE_DIR"
  105. local created=0
  106. # v2.1 경로 -> v3.0 경로 매핑
  107. # v2.1의 commands/ 디렉토리형 skill(8개)이 v3.0에서 skills/로 이전됨.
  108. # 기존 참조를 깨지 않도록 심볼릭 링크로 호환성 유지 (2027-04-01까지).
  109. local mappings=(
  110. "commands/debugging-strategies:skills/debugging-strategies"
  111. "commands/dependency-upgrade:skills/dependency-upgrade"
  112. "commands/evaluating-code-models:skills/evaluating-code-models"
  113. "commands/evaluating-llms-harness:skills/evaluating-llms-harness"
  114. "commands/extract-errors:skills/extract-errors"
  115. "commands/security-compliance:skills/security-compliance"
  116. "commands/stride-analysis-patterns:skills/stride-analysis-patterns"
  117. "commands/summarize:skills/summarize"
  118. )
  119. for mapping in "${mappings[@]}"; do
  120. local old_path="${mapping%%:*}"
  121. local new_path="${mapping##*:}"
  122. local new_target="$REPO_DIR/$new_path"
  123. local old_link="$target_base/$old_path"
  124. if [ -e "$new_target" ] && [ ! -e "$old_link" ]; then
  125. if [ "$DRY_RUN" -eq 1 ]; then
  126. echo " [DRY-RUN] would create compat link: $old_path -> $new_path"
  127. else
  128. mkdir -p "$(dirname "$old_link")"
  129. ln -sf "$new_target" "$old_link" 2>/dev/null && \
  130. echo -e " ${GREEN}✓${NC} compat link: $old_path -> $new_path" && \
  131. created=$((created + 1)) || true
  132. fi
  133. fi
  134. done
  135. if [ "$created" -eq 0 ] && [ "$DRY_RUN" -ne 1 ]; then
  136. echo " (no compat links needed)"
  137. fi
  138. }
  139. # Upgrade-mode summary
  140. print_upgrade_summary() {
  141. echo ""
  142. echo "=========================================="
  143. echo " Upgrade Summary"
  144. echo "=========================================="
  145. echo " Version : v4.1.0"
  146. echo " Mode : $([ "$DRY_RUN" -eq 1 ] && echo 'dry-run' || echo 'applied')"
  147. echo " Repo : $REPO_DIR"
  148. echo " Target : $CLAUDE_DIR"
  149. echo ""
  150. echo " Expected counts:"
  151. 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"
  152. echo ""
  153. echo " Next steps:"
  154. echo " 1. Review MIGRATION.md for detailed changes"
  155. echo " 2. Opt-in new hooks from hooks/examples/ as needed"
  156. echo " 3. Run 'claude mcp list' to verify 3 MCP servers"
  157. echo ""
  158. }
  159. # 1. Check dependencies
  160. check_deps() {
  161. echo "Checking dependencies..."
  162. local missing=()
  163. command -v node >/dev/null || missing+=("node")
  164. command -v jq >/dev/null || missing+=("jq")
  165. command -v git >/dev/null || missing+=("git")
  166. if [ ${#missing[@]} -gt 0 ]; then
  167. echo -e "${RED}Missing dependencies: ${missing[*]}${NC}"
  168. echo ""
  169. case "$PLATFORM" in
  170. macos)
  171. echo "Install with: brew install ${missing[*]}"
  172. ;;
  173. wsl|linux)
  174. echo "Install with: sudo apt install ${missing[*]}"
  175. 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
  176. ;;
  177. *)
  178. echo "Install with your package manager"
  179. ;;
  180. esac
  181. echo ""
  182. echo -e "${YELLOW}Need help? github.com/sangrokjung/claude-forge/issues${NC}"
  183. exit 1
  184. fi
  185. echo -e "${GREEN}All dependencies satisfied${NC}"
  186. }
  187. # 2. Initialize git submodules (cc-chips)
  188. init_submodules() {
  189. echo ""
  190. echo "Initializing git submodules..."
  191. cd "$REPO_DIR"
  192. git submodule update --init --recursive 2>/dev/null && \
  193. echo -e "${GREEN}Submodules initialized (cc-chips)${NC}" || \
  194. echo -e "${YELLOW}Submodule init skipped (may already be initialized)${NC}"
  195. }
  196. # 3. Backup existing config
  197. backup() {
  198. if [ -d "$CLAUDE_DIR" ]; then
  199. local backup_dir="$CLAUDE_DIR.backup.$(date +%Y%m%d_%H%M%S)"
  200. echo ""
  201. echo -e "${YELLOW}Existing ~/.claude found${NC}"
  202. # Upgrade mode: skip wholesale move, just refresh symlinks in place
  203. if [ "$UPGRADE_MODE" -eq 1 ]; then
  204. echo " Upgrade mode: preserving $CLAUDE_DIR (symlinks will be refreshed)."
  205. return 0
  206. fi
  207. read -p "Backup to $backup_dir? (y/n) " -n 1 -r
  208. echo ""
  209. if [[ $REPLY =~ ^[Yy]$ ]]; then
  210. if [ "$DRY_RUN" -eq 1 ]; then
  211. echo " [DRY-RUN] would mv $CLAUDE_DIR -> $backup_dir"
  212. else
  213. mv "$CLAUDE_DIR" "$backup_dir"
  214. echo -e "${GREEN}Backed up to $backup_dir${NC}"
  215. fi
  216. else
  217. echo "Skipping backup. Existing files may be overwritten."
  218. fi
  219. fi
  220. }
  221. # 4. Create symlinks (or copies on WSL cross-filesystem)
  222. link_files() {
  223. echo ""
  224. # WSL: if repo is on Windows filesystem (/mnt/c/...), use copies instead of symlinks
  225. local use_copy=false
  226. if [[ "$PLATFORM" == "wsl" ]] && [[ "$REPO_DIR" == /mnt/* ]]; then
  227. echo -e "${YELLOW}WSL detected with Windows filesystem path. Using copies instead of symlinks.${NC}"
  228. echo " Tip: Clone repo to ~/claude-forge for symlink support."
  229. use_copy=true
  230. fi
  231. if [ "$use_copy" = true ]; then
  232. echo "Copying configuration files..."
  233. else
  234. echo "Creating symlinks..."
  235. fi
  236. if [ "$DRY_RUN" -eq 1 ]; then
  237. echo " [DRY-RUN] would mkdir -p $CLAUDE_DIR"
  238. else
  239. mkdir -p "$CLAUDE_DIR"
  240. fi
  241. # Directories
  242. # NOTE: cc-chips is a git submodule; if the user cloned without
  243. # --recurse-submodules the directory exists but is empty, which would
  244. # create a broken symlink that statusLine would then dereference. Skip
  245. # with a one-line hint in that case so the rest of the install still
  246. # succeeds.
  247. for dir in agents rules commands scripts skills hooks libs reference cc-chips cc-chips-custom; do
  248. if [ -d "$REPO_DIR/$dir" ]; then
  249. if [ "$dir" = "cc-chips" ] && [ -z "$(ls -A "$REPO_DIR/$dir" 2>/dev/null)" ]; then
  250. echo -e " ${YELLOW}!${NC} Skipping cc-chips/: submodule not initialized."
  251. echo " Run: git submodule update --init cc-chips"
  252. echo " (statusLine chip renderer will be disabled until then.)"
  253. continue
  254. fi
  255. if [ "$DRY_RUN" -eq 1 ]; then
  256. echo " [DRY-RUN] would refresh $dir/"
  257. continue
  258. fi
  259. rm -rf "$CLAUDE_DIR/$dir" 2>/dev/null || true
  260. if [ "$use_copy" = true ]; then
  261. cp -r "$REPO_DIR/$dir" "$CLAUDE_DIR/$dir"
  262. echo " Copied: $dir/"
  263. else
  264. ln -sf "$REPO_DIR/$dir" "$CLAUDE_DIR/$dir"
  265. echo " Linked: $dir/"
  266. fi
  267. fi
  268. done
  269. # Files
  270. for file in settings.json; do
  271. if [ -f "$REPO_DIR/$file" ]; then
  272. if [ "$DRY_RUN" -eq 1 ]; then
  273. echo " [DRY-RUN] would refresh $file"
  274. continue
  275. fi
  276. rm -f "$CLAUDE_DIR/$file" 2>/dev/null || true
  277. if [ "$use_copy" = true ]; then
  278. cp "$REPO_DIR/$file" "$CLAUDE_DIR/$file"
  279. echo " Copied: $file"
  280. else
  281. ln -sf "$REPO_DIR/$file" "$CLAUDE_DIR/$file"
  282. echo " Linked: $file"
  283. fi
  284. fi
  285. done
  286. }
  287. # 4b. Validate mcp-servers.json for v3.0 (3 core entries)
  288. validate_mcp_v3() {
  289. local mcp_json="$REPO_DIR/mcp-servers.json"
  290. if [ ! -f "$mcp_json" ] || ! command -v jq >/dev/null; then
  291. return 0
  292. fi
  293. echo ""
  294. echo "Validating mcp-servers.json (v3.0 minimal profile)..."
  295. # v3.0 schema uses `.servers.<name>`; legacy v2.x used `.install_commands.<name>`
  296. local expected=("playwright" "context7" "jina-reader")
  297. local missing=()
  298. for s in "${expected[@]}"; do
  299. local present=0
  300. if jq -e --arg s "$s" '.servers[$s] // empty' "$mcp_json" >/dev/null 2>&1; then
  301. present=1
  302. elif jq -e --arg s "$s" '.install_commands[$s] // empty' "$mcp_json" >/dev/null 2>&1; then
  303. present=1
  304. fi
  305. [ "$present" -eq 0 ] && missing+=("$s")
  306. done
  307. local server_count
  308. server_count=$(jq -r '.servers | length // 0' "$mcp_json" 2>/dev/null || echo 0)
  309. if [ ${#missing[@]} -eq 0 ]; then
  310. echo -e " ${GREEN}✓${NC} v3.0 core MCP entries present (3/3, total=$server_count)"
  311. else
  312. echo -e " ${YELLOW}!${NC} Missing v3.0 MCP entries: ${missing[*]}"
  313. echo " See docs/MCP-MIGRATION.md for remediation."
  314. fi
  315. }
  316. # 5. Apply CC CHIPS custom overlay
  317. apply_cc_chips_custom() {
  318. local custom_dir="$REPO_DIR/cc-chips-custom"
  319. if [ -d "$custom_dir" ]; then
  320. echo ""
  321. echo "Applying CC CHIPS custom overlay..."
  322. if [ "$DRY_RUN" -eq 1 ]; then
  323. echo " [DRY-RUN] would overlay engine.sh + themes/*.sh"
  324. return 0
  325. fi
  326. local target="$CLAUDE_DIR/cc-chips"
  327. if [ -f "$custom_dir/engine.sh" ] && [ -d "$target" ]; then
  328. cp "$custom_dir/engine.sh" "$target/engine.sh"
  329. chmod +x "$target/engine.sh"
  330. echo -e " ${GREEN}✓${NC} engine.sh (model detection + session ID + cache stats)"
  331. fi
  332. if [ -d "$custom_dir/themes" ] && [ -d "$target/themes" ]; then
  333. cp "$custom_dir/themes/"*.sh "$target/themes/" 2>/dev/null
  334. echo -e " ${GREEN}✓${NC} themes/ (stats chip colors)"
  335. fi
  336. echo -e "${GREEN}CC CHIPS custom overlay applied!${NC}"
  337. fi
  338. }
  339. # 6. Install MCP servers
  340. install_mcp_servers() {
  341. echo ""
  342. echo "Installing MCP servers..."
  343. # Check if claude CLI is available
  344. if ! command -v claude >/dev/null; then
  345. echo -e "${YELLOW}Claude CLI not found. Skipping MCP server installation.${NC}"
  346. echo "Install Claude CLI first, then re-run this script."
  347. return 0
  348. fi
  349. read -p "Install recommended MCP servers? (y/n) " -n 1 -r
  350. echo ""
  351. if [[ ! $REPLY =~ ^[Yy]$ ]]; then
  352. echo "Skipping MCP server installation."
  353. return 0
  354. fi
  355. # Read install commands from mcp-servers.json if available
  356. local mcp_json="$REPO_DIR/mcp-servers.json"
  357. if [ -f "$mcp_json" ] && command -v jq >/dev/null; then
  358. echo " Installing from mcp-servers.json..."
  359. # Core servers (no API key required)
  360. local core_servers=("context7" "sequential-thinking" "memory" "youtube-transcript" "remotion" "playwright" "desktop-commander")
  361. for server in "${core_servers[@]}"; do
  362. local cmd
  363. cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
  364. if [ -n "$cmd" ]; then
  365. echo " Installing $server..."
  366. eval "$cmd" 2>/dev/null && \
  367. echo -e " ${GREEN}✓${NC} $server" || \
  368. echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
  369. fi
  370. done
  371. # Optional servers
  372. echo ""
  373. echo -e "${YELLOW}Optional servers (may require authentication):${NC}"
  374. local optional_servers=("exa" "gmail" "google-calendar" "n8n-mcp" "hyperbrowser" "stitch" "sentry" "supabase" "github")
  375. for server in "${optional_servers[@]}"; do
  376. local cmd
  377. cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
  378. if [ -n "$cmd" ]; then
  379. read -p " Install $server? (y/n) " -n 1 -r
  380. echo ""
  381. if [[ $REPLY =~ ^[Yy]$ ]]; then
  382. eval "$cmd" 2>/dev/null && \
  383. echo -e " ${GREEN}✓${NC} $server" || \
  384. echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
  385. fi
  386. fi
  387. done
  388. # Korean public data servers
  389. echo ""
  390. read -p " Install Korean public data servers (NTS, NPS, PPS, FSC, MSDS)? (y/n) " -n 1 -r
  391. echo ""
  392. if [[ $REPLY =~ ^[Yy]$ ]]; then
  393. for server in "data-go-nts" "data-go-nps" "data-go-pps" "data-go-fsc" "data-go-msds"; do
  394. local cmd
  395. cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
  396. if [ -n "$cmd" ]; then
  397. eval "$cmd" 2>/dev/null && \
  398. echo -e " ${GREEN}✓${NC} $server" || \
  399. echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
  400. fi
  401. done
  402. fi
  403. # Financial data servers
  404. echo ""
  405. read -p " Install financial data servers (CoinGecko, Alpha Vantage, FRED, Korea Stock)? (y/n) " -n 1 -r
  406. echo ""
  407. if [[ $REPLY =~ ^[Yy]$ ]]; then
  408. for server in "coingecko" "alpha-vantage" "fred" "korea-stock"; do
  409. local cmd
  410. cmd=$(jq -r ".install_commands.\"$server\" // empty" "$mcp_json")
  411. if [ -n "$cmd" ]; then
  412. eval "$cmd" 2>/dev/null && \
  413. echo -e " ${GREEN}✓${NC} $server" || \
  414. echo -e " ${YELLOW}!${NC} $server (already installed or failed)"
  415. fi
  416. done
  417. fi
  418. else
  419. # Fallback: minimal install without mcp-servers.json
  420. echo " Installing core MCP servers..."
  421. claude mcp add context7 -- npx -y @upstash/context7-mcp 2>/dev/null && \
  422. echo -e " ${GREEN}✓${NC} context7" || echo -e " ${YELLOW}!${NC} context7"
  423. claude mcp add playwright -- npx @playwright/mcp@latest 2>/dev/null && \
  424. echo -e " ${GREEN}✓${NC} playwright" || echo -e " ${YELLOW}!${NC} playwright"
  425. claude mcp add memory -- npx -y @modelcontextprotocol/server-memory 2>/dev/null && \
  426. echo -e " ${GREEN}✓${NC} memory" || echo -e " ${YELLOW}!${NC} memory"
  427. claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking 2>/dev/null && \
  428. echo -e " ${GREEN}✓${NC} sequential-thinking" || echo -e " ${YELLOW}!${NC} sequential-thinking"
  429. fi
  430. echo ""
  431. echo -e "${GREEN}MCP server installation complete!${NC}"
  432. echo "Run 'claude mcp list' to verify installed servers."
  433. }
  434. # 7. Install external skills (npx skills)
  435. install_external_skills() {
  436. echo ""
  437. echo "Installing external skills..."
  438. if ! command -v npx >/dev/null; then
  439. echo -e "${YELLOW}npx not found. Skipping external skills installation.${NC}"
  440. return 0
  441. fi
  442. read -p "Install external skills (Superpowers, Humanizer, UI/UX Pro Max, Find Skills)? (y/n) " -n 1 -r
  443. echo ""
  444. if [[ ! $REPLY =~ ^[Yy]$ ]]; then
  445. echo "Skipping external skills installation."
  446. return 0
  447. fi
  448. echo " Installing Superpowers (14 skills)..."
  449. npx -y skills add obra/superpowers -y -g 2>/dev/null && \
  450. echo -e " ${GREEN}✓${NC} superpowers" || echo -e " ${YELLOW}!${NC} superpowers (failed)"
  451. echo " Installing Humanizer..."
  452. npx -y skills add blader/humanizer -y -g 2>/dev/null && \
  453. echo -e " ${GREEN}✓${NC} humanizer" || echo -e " ${YELLOW}!${NC} humanizer (failed)"
  454. echo " Installing UI/UX Pro Max..."
  455. npx -y skills add nextlevelbuilder/ui-ux-pro-max-skill -y -g 2>/dev/null && \
  456. echo -e " ${GREEN}✓${NC} ui-ux-pro-max" || echo -e " ${YELLOW}!${NC} ui-ux-pro-max (failed)"
  457. echo " Installing Find Skills..."
  458. npx -y skills add vercel-labs/skills -y -g 2>/dev/null && \
  459. echo -e " ${GREEN}✓${NC} find-skills" || echo -e " ${YELLOW}!${NC} find-skills (failed)"
  460. echo ""
  461. echo -e "${GREEN}External skills installation complete!${NC}"
  462. }
  463. # 8. Setup shell aliases
  464. setup_shell_aliases() {
  465. echo ""
  466. echo "Setting up shell aliases..."
  467. local shell_rc=""
  468. if [ -n "$ZSH_VERSION" ] || [ -f "$HOME/.zshrc" ]; then
  469. shell_rc="$HOME/.zshrc"
  470. elif [ -f "$HOME/.bashrc" ]; then
  471. shell_rc="$HOME/.bashrc"
  472. fi
  473. if [ -z "$shell_rc" ]; then
  474. echo -e "${YELLOW}No .zshrc or .bashrc found. Skipping aliases.${NC}"
  475. return 0
  476. fi
  477. local marker="# Claude Code aliases"
  478. if grep -q "$marker" "$shell_rc" 2>/dev/null; then
  479. echo -e " ${GREEN}✓${NC} Aliases already configured in $(basename "$shell_rc")"
  480. return 0
  481. fi
  482. cat >> "$shell_rc" << 'ALIASES'
  483. # Claude Code aliases
  484. alias cc='claude'
  485. alias ccr='claude --resume'
  486. ALIASES
  487. echo -e " ${GREEN}✓${NC} Added aliases to $(basename "$shell_rc")"
  488. echo " cc → claude"
  489. echo " ccr → claude --resume"
  490. }
  491. # 9. Verify installation
  492. verify() {
  493. echo ""
  494. echo "Verifying installation..."
  495. local errors=0
  496. for item in agents rules commands scripts skills cc-chips cc-chips-custom hooks libs reference settings.json; do
  497. if [ -L "$CLAUDE_DIR/$item" ] && [ ! -e "$CLAUDE_DIR/$item" ]; then
  498. echo -e " ${RED}✗${NC} $item (broken symlink)"
  499. errors=$((errors + 1))
  500. elif [ -L "$CLAUDE_DIR/$item" ] || [ -e "$CLAUDE_DIR/$item" ]; then
  501. echo -e " ${GREEN}✓${NC} $item"
  502. else
  503. echo -e " ${RED}✗${NC} $item (not found)"
  504. errors=$((errors + 1))
  505. fi
  506. done
  507. return $errors
  508. }
  509. # 10. Write forge metadata
  510. write_meta() {
  511. echo ""
  512. echo "Writing forge metadata..."
  513. # install_mode 판단: agents가 symlink이면 symlink, 아니면 copy
  514. local install_mode="symlink"
  515. if [ ! -L "$CLAUDE_DIR/agents" ] && [ -d "$CLAUDE_DIR/agents" ]; then
  516. install_mode="copy"
  517. fi
  518. # plugin.json에서 버전 읽기
  519. local version="1.0.0"
  520. if [ -f "$REPO_DIR/.claude-plugin/plugin.json" ] && command -v jq >/dev/null; then
  521. version=$(jq -r '.version // "1.0.0"' "$REPO_DIR/.claude-plugin/plugin.json")
  522. fi
  523. # git 정보
  524. local git_commit=""
  525. local remote_url=""
  526. if command -v git >/dev/null && [ -d "$REPO_DIR/.git" ]; then
  527. git_commit=$(cd "$REPO_DIR" && git rev-parse --short HEAD 2>/dev/null || echo "")
  528. remote_url=$(cd "$REPO_DIR" && git remote get-url origin 2>/dev/null || echo "")
  529. fi
  530. local now
  531. now=$(date +"%Y-%m-%dT%H:%M:%S%z" 2>/dev/null || date +"%Y-%m-%dT%H:%M:%S")
  532. # 기존 메타파일이 있으면 installed_at 보존
  533. local installed_at="$now"
  534. if [ -f "$CLAUDE_DIR/.forge-meta.json" ] && command -v jq >/dev/null; then
  535. local prev_installed
  536. prev_installed=$(jq -r '.installed_at // ""' "$CLAUDE_DIR/.forge-meta.json")
  537. if [ -n "$prev_installed" ] && [ "$prev_installed" != "null" ]; then
  538. installed_at="$prev_installed"
  539. fi
  540. fi
  541. # jq로 안전하게 JSON 생성 (경로 인젝션 방지)
  542. jq -n \
  543. --arg repo_path "$REPO_DIR" \
  544. --arg install_mode "$install_mode" \
  545. --arg installed_at "$installed_at" \
  546. --arg updated_at "$now" \
  547. --arg version "$version" \
  548. --arg git_commit "$git_commit" \
  549. --arg remote_url "$remote_url" \
  550. --arg platform "$PLATFORM" \
  551. '{
  552. repo_path: $repo_path,
  553. install_mode: $install_mode,
  554. installed_at: $installed_at,
  555. updated_at: $updated_at,
  556. version: $version,
  557. git_commit: $git_commit,
  558. remote_url: $remote_url,
  559. platform: $platform
  560. }' > "$CLAUDE_DIR/.forge-meta.json"
  561. chmod 600 "$CLAUDE_DIR/.forge-meta.json"
  562. echo -e " ${GREEN}✓${NC} .forge-meta.json"
  563. }
  564. # 11. Install work tracker (local usage log; remote sync is opt-in)
  565. install_work_tracker() {
  566. local wt_script="$REPO_DIR/setup/work-tracker-install.sh"
  567. if [ -f "$wt_script" ]; then
  568. echo ""
  569. # Remote sync needs scripts/work-tracker-sync.sh, which is not shipped: the
  570. # backend differs per user. Without it the hooks still log locally to
  571. # ~/.claude/work-log/buffer.jsonl, so do not promise a sync we cannot install.
  572. read -p "Install Work Tracker (logs Claude Code usage to ~/.claude/work-log)? (y/n) " -n 1 -r
  573. echo ""
  574. if [[ $REPLY =~ ^[Yy]$ ]]; then
  575. REPO_DIR="$REPO_DIR" bash "$wt_script"
  576. else
  577. echo "Skipping Work Tracker installation."
  578. fi
  579. fi
  580. }
  581. # Main
  582. main() {
  583. if [ "$UPGRADE_MODE" -eq 1 ]; then
  584. print_upgrade_banner
  585. fi
  586. check_deps
  587. init_submodules
  588. backup
  589. link_files
  590. apply_cc_chips_custom
  591. validate_mcp_v3
  592. # v3.0 compat symlinks (upgrade mode only)
  593. if [ "$UPGRADE_MODE" -eq 1 ]; then
  594. echo ""
  595. echo "Creating v3.0 compat links..."
  596. create_v3_compat_links
  597. fi
  598. if [ "$DRY_RUN" -eq 1 ]; then
  599. echo ""
  600. echo -e "${YELLOW}[DRY-RUN] Skipping verify/metadata/MCP/skills/tracker steps.${NC}"
  601. if [ "$UPGRADE_MODE" -eq 1 ]; then
  602. print_upgrade_summary
  603. fi
  604. return 0
  605. fi
  606. if verify; then
  607. echo ""
  608. echo -e "${GREEN}Symlinks created successfully!${NC}"
  609. # Write forge metadata
  610. write_meta
  611. # Setup shell aliases
  612. setup_shell_aliases
  613. # Install MCP servers
  614. install_mcp_servers
  615. # Install external skills
  616. install_external_skills
  617. # Install work tracker
  618. install_work_tracker
  619. if [ "$UPGRADE_MODE" -eq 1 ]; then
  620. print_upgrade_summary
  621. fi
  622. echo ""
  623. cat << COMPLETE
  624. ${GREEN}╔══════════════════════════════════════════════════════╗
  625. ║ Claude Forge 설치 완료! ║
  626. ╠══════════════════════════════════════════════════════╣
  627. ║ 16 agents · 35 commands · 6-layer security ║
  628. ╚══════════════════════════════════════════════════════╝${NC}
  629. 처음이신가요? 이것만 하세요:
  630. 1. 새 터미널을 열고 'claude' 실행
  631. 2. ${GREEN}/guide${NC} 입력 — 3분 인터랙티브 가이드
  632. 자주 쓰는 TOP 5:
  633. /plan AI가 구현 계획을 세워줍니다
  634. /tdd 테스트 먼저 만들고 코드 작성
  635. /code-review 코드 보안+품질 검사
  636. /handoff-verify 빌드/테스트/린트 자동 검증
  637. /auto 계획부터 PR까지 원버튼 자동
  638. ${YELLOW}★ Star: github.com/sangrokjung/claude-forge${NC}
  639. ${YELLOW}? Issues: github.com/sangrokjung/claude-forge/issues${NC}
  640. COMPLETE
  641. else
  642. echo ""
  643. echo -e "${RED}Installation completed with errors${NC}"
  644. exit 1
  645. fi
  646. }
  647. main "$@"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.