Skip to content
Back to search

ClaudeForge

A CLAUDE.md Generator and Maintenance tool for for Claude Code to create high-quality CLAUDE.md instruction files — aligned with Anthropic’s best practices for Claude Code.

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/alirezarezvani--claudeforge/badge.svg)](/listings/alirezarezvani--claudeforge)

HTML

<a href="/listings/alirezarezvani--claudeforge"><img src="/api/listings/alirezarezvani--claudeforge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

Installation

**Claude Code Plugin (recommended)**

ClaudeForge ships as a Claude Code plugin. From any Claude Code session:

/plugin marketplace add alirezarezvani/ClaudeForge
/plugin install claudeforge

This installs every component (skills, slash commands, guardian agent) and registers `/enhance-claude-md` and `/sync-claude-md` for any project. Works the same at the user level (available everywhere) or scoped to a single project.

**macOS / Linux**

curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash

**Windows (PowerShell)**

iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex

**Manual Installation**

git clone https://github.com/alirezarezvani/ClaudeForge.git
cd ClaudeForge
./install.sh  # or .\install.ps1 on Windows

Usage

After installation, restart Claude Code and run:

/enhance-claude-md

That's it! The command will: 1. ✅ Explore your project structure 2. ✅ Detect tech stack and project type 3. ✅ Show discoveries and ask for confirmation 4. ✅ Create customized CLAUDE.md file(s) 5. ✅ Apply best practices and native format

---

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.

README.md · README · 326 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ClaudeForge
  2. > **Automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects**
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/alirezarezvani/ClaudeForge/releases)
  5. [![Claude Code](https://img.shields.io/badge/Claude_Code-2.1.4%2B-purple.svg)](https://claude.com/claude-code)
  6. [![CI/CD](https://img.shields.io/badge/CI/CD-GitHub_Actions-2088FF.svg)](https://github.com/alirezarezvani/ClaudeForge/actions)
  7. [![Quality Gates](https://img.shields.io/badge/Quality_Gates-Automated-success.svg)](docs/GITHUB_WORKFLOWS.md)
  8. ClaudeForge is a comprehensive toolkit that eliminates the tedious process of manually creating and maintaining CLAUDE.md files. With intelligent analysis, automated generation, and background maintenance, your CLAUDE.md files stay perfectly synchronized with your codebase.
  9. ---
  10. ## 🆕 What's New
  11. - **Installable Claude Code plugin** — manifest at `.claude-plugin/plugin.json`; install with `/plugin marketplace add alirezarezvani/ClaudeForge && /plugin install claudeforge`
  12. - **Hard 150-line cap per CLAUDE.md** — enforced deterministically by `hooks/hooks.json` on `PostToolUse(Edit|Write)` *and* `InstructionsLoaded` (every `load_reason`); larger projects spread content across chained sub-files via `@path` imports
  13. - **`/sync-claude-md`** — walks every CLAUDE.md, prunes stale references, splits when over the cap, repairs root ↔ sub chains
  14. - **`/sync-claude-md --weekly`** — orchestrates three forked task-style skills in parallel: `claude-md-drift-audit`, `claude-md-link-check`, `claude-md-dependency-rescan`
  15. - **Karpathy behavioural guidelines** auto-embedded in every generated CLAUDE.md and installed as a standalone `~/.claude/skills/karpathy-guidelines/` skill scoped to code-file globs
  16. - **`AGENTS.md` / `.cursorrules` / `.windsurfrules` interop** — `/enhance-claude-md` detects sibling instruction files and chains them via `@`-imports instead of overwriting
  17. - **`CLAUDE.local.md` personal tier** — per-developer overrides exempt from the cap, gitignored automatically
  18. - **Layered hook config** — `hooks/hooks-config.json` (committed defaults) + `hooks/hooks-config.local.json` (gitignored) lets developers opt out per machine
  19. - **Lifecycle hooks**: `SessionStart`, `PreToolUse`, `PostToolUse`, `InstructionsLoaded`, `Stop` (one-line drift summary at session end)
  20. - **Guardian agent** runs `model: haiku` with a fail-closed contract (Skill-tool only, never auto-commits, aborts on missing validated output)
  21. 👉 **Upgrading from v1.x?** See [docs/MIGRATION_V2.md](docs/MIGRATION_V2.md).
  22. ---
  23. ## ✨ Features
  24. - 🚀 **Interactive Initialization** - Explores your repository, detects project context, and creates customized CLAUDE.md files through conversational workflow
  25. - ✅ **Intelligent Analysis** - Scans and evaluates existing CLAUDE.md files with quality scoring (0-100) and actionable recommendations
  26. - 🔧 **Smart Enhancement** - Adds missing sections and improves structure automatically
  27. - 🛡️ **Background Maintenance** - Guardian agent keeps CLAUDE.md synchronized with codebase changes
  28. - 📦 **Modular Architecture** - Supports complex projects with context-specific files (backend/, frontend/, database/)
  29. - 🎯 **100% Native Format** - All generated files follow official Claude Code format with project structure diagrams, setup instructions, and architecture sections
  30. - 🛠️ **Tech Stack Customization** - Tailors guidelines to TypeScript, Python, Go, React, Vue, FastAPI, and more
  31. - 👥 **Team Size Adaptation** - Adjusts complexity based on team size (solo, small, medium, large)
  32. ---
  33. ## 📦 What's Included
  34. ### Skills
  35. 1. **`claudeforge-skill`** (`skill/SKILL.md`) — core analysis / validation / generation engine; runs on `model: haiku`. Scoped via `paths:` to `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `.cursorrules`, `.windsurfrules`, and `.claude/rules/*.md` so it auto-loads only when those files are touched.
  36. 2. **`karpathy-guidelines`** (`skill/karpathy-guidelines/SKILL.md`) — Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution. Embedded into every generated CLAUDE.md and installed as a standalone skill `paths:`-scoped to ~23 source-file extensions. Adapted with attribution from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills).
  37. 3. **`claude-md-drift-audit`** (`skill/claude-md-drift-audit/SKILL.md`, forked + `agent: Explore`) — walks the last N days of git history and flags every CLAUDE.md line that references deleted paths, renamed paths, or removed dependencies. Read-only. `/claude-md-drift-audit [days=7]`.
  38. 4. **`claude-md-link-check`** (`skill/claude-md-link-check/SKILL.md`, forked + `agent: Explore`) — verifies every `@path` chain import and every relative markdown link inside every CLAUDE.md resolves. Read-only. `/claude-md-link-check [path-glob]`.
  39. 5. **`claude-md-dependency-rescan`** (`skill/claude-md-dependency-rescan/SKILL.md`, forked + `agent: Explore`) — diffs declared dependencies (`package.json` / `requirements.txt` / `pyproject.toml` / `go.mod` / `Cargo.toml`) against the Tech Stack section of every CLAUDE.md. Read-only. `/claude-md-dependency-rescan [manifest]`.
  40. ### Slash commands
  41. - **`/enhance-claude-md`** (`command/enhance-claude-md.md`) — multi-phase init/enhance workflow with `argument-hint`, `when_to_use`, `allowed-tools`, and `disallowedTools` (blocks `WebFetch` / `WebSearch`). Delegates deep codebase scans to the Explore subagent.
  42. - **`/sync-claude-md`** (`command/sync-claude-md.md`) — inventory → prune stale refs → enforce the 150-line cap → repair root ↔ sub chain. **New `--weekly` flag** orchestrates the three audit skills in parallel before doing sync work.
  43. - **`/claude-to-agents`** (`command/claude-to-agents.md`) — convert the project's CLAUDE.md tree into an `AGENTS.md` for Codex / Gemini Code Assist / any tool honouring the AGENTS.md convention. Three modes: `--symlink` (one source of truth, default on macOS/Linux), `--copy` (snapshot), `--inline-chain` (flattens the `@path` chain into one self-contained file — recommended for modular projects since Codex/Gemini don't auto-resolve `@` imports). Backs up an existing AGENTS.md before overwrite.
  44. ### Agent
  45. - **`claude-md-guardian`** (`agent/claude-md-guardian.md`) — background maintenance. Runs `model: haiku` with a fail-closed contract: Skill-tool only, aborts on missing validated output, never auto-commits, respects the local hook config.
  46. ### Hooks
  47. - **`hooks/hooks.json`** — wires `PostToolUse(Write|Edit)`, `InstructionsLoaded` (all five `load_reason` values), and `Stop` events to scripts under `hooks/`.
  48. - **`hooks/validate-claude-md.py`** — enforces the 150-line cap deterministically at load time *and* write time; exempts `*.local.md`; exits with stderr feedback on violation.
  49. - **`hooks/audit-claude-md.py`** — `Stop` hook; one-line CLAUDE.md health summary printed at session end (total tracked / over cap / near cap).
  50. - **`hooks/hooks-config.json`** + **`hooks/hooks-config.local.json`** — layered config; per-developer overrides without forking the shipped manifest.
  51. ---
  52. ## 🚀 Quick Start
  53. ### Installation
  54. #### **Claude Code Plugin (recommended)**
  55. ClaudeForge ships as a Claude Code plugin. From any Claude Code session:
  56. ```text
  57. /plugin marketplace add alirezarezvani/ClaudeForge
  58. /plugin install claudeforge
  59. ```
  60. This installs every component (skills, slash commands, guardian agent) and registers `/enhance-claude-md` and `/sync-claude-md` for any project. Works the same at the user level (available everywhere) or scoped to a single project.
  61. #### **macOS / Linux**
  62. ```bash
  63. curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 91 on GitHub
  64. ```
  65. #### **Windows (PowerShell)**
  66. ```powershell
  67. iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex
  68. ```
  69. #### **Manual Installation**
  70. ```bash
  71. git clone https://github.com/alirezarezvani/ClaudeForge.git
  72. cd ClaudeForge
  73. ./install.sh # or .\install.ps1 on Windows
  74. ```
  75. ### Usage
  76. After installation, restart Claude Code and run:
  77. ```bash
  78. /enhance-claude-md
  79. ```
  80. That's it! The command will:
  81. 1. ✅ Explore your project structure
  82. 2. ✅ Detect tech stack and project type
  83. 3. ✅ Show discoveries and ask for confirmation
  84. 4. ✅ Create customized CLAUDE.md file(s)
  85. 5. ✅ Apply best practices and native format
  86. ---
  87. ## 💡 Use Cases
  88. ### **New Project (No CLAUDE.md)**
  89. ```bash
  90. /enhance-claude-md
  91. # Claude explores your repository and responds:
  92. #
  93. # "Based on my exploration, here's what I discovered:
  94. #
  95. # 📦 Project Type: Full-Stack Application
  96. # 🛠️ Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
  97. # 👥 Team Size: Small (5 developers)
  98. # 🚀 Development Phase: MVP
  99. #
  100. # 📋 Recommended Structure:
  101. # - Root CLAUDE.md (navigation hub, ~100 lines)
  102. # - backend/CLAUDE.md (API guidelines, ~150 lines)
  103. # - frontend/CLAUDE.md (React guidelines, ~175 lines)
  104. #
  105. # Would you like me to create these files?"
  106. #
  107. # You: "Yes"
  108. #
  109. # ✅ CLAUDE.md created (108 lines)
  110. # ✅ backend/CLAUDE.md created (156 lines)
  111. # ✅ frontend/CLAUDE.md created (182 lines)
  112. ```
  113. ### **Existing Project (Needs Improvement)**
  114. ```bash
  115. /enhance-claude-md
  116. # Claude analyzes your current CLAUDE.md:
  117. #
  118. # "Quality Score: 65/100
  119. #
  120. # Missing Sections:
  121. # - Project Structure (ASCII diagram)
  122. # - Setup & Installation
  123. # - Architecture
  124. #
  125. # Would you like me to enhance your CLAUDE.md with these sections?"
  126. #
  127. # You: "Yes"
  128. #
  129. # ✅ CLAUDE.md enhanced (+2 sections, quality score: 65 → 88)
  130. ```
  131. ### **Background Maintenance**
  132. ```bash
  133. # You start a new Claude Code session
  134. # Guardian agent automatically checks for changes
  135. #
  136. # ✅ CLAUDE.md updated:
  137. # - Tech Stack: Added 2 dependencies (react-query, tailwindcss)
  138. # - Project Structure: Updated diagram with new components/ directory
  139. # - Setup & Installation: New environment variables
  140. #
  141. # Changes: 3 sections, 12 lines
  142. ```
  143. ---
  144. ## 📚 Documentation
  145. | Document | Description |
  146. |----------|-------------|
  147. | [Quick Start Guide](docs/QUICK_START.md) | 5-minute tutorial to get started |
  148. | [Installation Guide](docs/INSTALLATION.md) | Detailed installation instructions and troubleshooting |
  149. | [Architecture Overview](docs/ARCHITECTURE.md) | How components work together |
  150. | [GitHub Workflows](docs/GITHUB_WORKFLOWS.md) | CI/CD automation and quality gates |
  151. | [Branching Strategy](docs/BRANCHING_STRATEGY.md) | Branch flow and protection rules |
  152. | [Troubleshooting](docs/TROUBLESHOOTING.md) | Common issues and solutions |
  153. | [Contributing Guide](docs/CONTRIBUTING.md) | How to contribute to ClaudeForge |
  154. ---
  155. ## 📖 Examples
  156. See the [examples/](examples/) directory for:
  157. - Basic usage scenarios
  158. - Modular architecture setup
  159. - Integration with existing projects
  160. - Advanced customization
  161. ---
  162. ## 🔧 Components Deep Dive
  163. ### **Skill: claudeforge-skill**
  164. **Core Capabilities:**
  165. - **Analysis** - Scans existing CLAUDE.md files for quality and completeness
  166. - **Validation** - Checks against Anthropic guidelines and best practices
  167. - **Generation** - Creates new CLAUDE.md files from scratch
  168. - **Enhancement** - Adds missing sections and improves structure
  169. - **Template Selection** - Chooses appropriate templates based on project context
  170. **Quality Scoring (0-100):**
  171. - Length appropriateness (25 pts)
  172. - Section completeness (25 pts)
  173. - Formatting quality (20 pts)
  174. - Content specificity (15 pts)
  175. - Modular organization (15 pts)
  176. ### **Slash Command: /enhance-claude-md**
  177. **Multi-phase workflow** (Discovery → Analysis → Task). Discovery delegates the deep codebase walk to the Explore subagent so it doesn't bloat the calling session. Phase 1 also detects sibling `AGENTS.md` / `.cursorrules` / `.windsurfrules` and chains them via `@`-imports rather than overwriting. Phase 3 invokes `claudeforge-skill` via the Skill tool.
  178. ### **Slash Command: /sync-claude-md (with `--weekly`)**
  179. Default mode: inventory every CLAUDE.md, prune stale references, enforce the 150-line cap by splitting into sub-files, repair the root ↔ sub chain. With `--weekly`, **Phase 0** issues the three forked audit skills (`claude-md-drift-audit`, `claude-md-link-check`, `claude-md-dependency-rescan`) in parallel via the Skill tool, aggregates their findings under `## Weekly Audit Summary`, then proceeds. Each forked skill runs in an isolated subagent context (`context: fork`, `agent: Explore`) so audit work doesn't bloat the calling session.
  180. ### **Agent: claude-md-guardian**
  181. Runs `model: haiku`, `fork_safe: true`. Hook frontmatter uses Anthropic's canonical keyed-object schema (events: `SessionStart`, `PreToolUse`, `PostToolUse`, `InstructionsLoaded`). **Fail-closed contract**: invokes `claudeforge-skill` exclusively through the Skill tool (never inlines SKILL.md), aborts on missing validated output, never auto-commits, respects `hooks/hooks-config.local.json`.
  182. ---
  183. ## 🎯 Requirements
  184. - **Claude Code** 2.0 or later
  185. - **Git** (recommended for change detection)
  186. - **Operating Systems:** macOS, Linux, Windows (PowerShell)
  187. ---
  188. ## 🤝 Contributing
  189. We welcome contributions! Please see our [Contributing Guide](docs/CONTRIBUTING.md) for details.
  190. ### Quick Contribution Steps:
  191. 1. Fork the repository
  192. 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
  193. 3. Commit your changes (`git commit -m 'Add amazing feature'`)
  194. 4. Push to the branch (`git push origin feature/amazing-feature`)
  195. 5. Open a Pull Request
  196. ---
  197. ## 🐛 Issues & Support
  198. - **Bug Reports:** [GitHub Issues](https://github.com/alirezarezvani/ClaudeForge/issues)
  199. - **Feature Requests:** [GitHub Discussions](https://github.com/alirezarezvani/ClaudeForge/discussions)
  200. - **Documentation:** [docs/](docs/)
  201. ---
  202. ## 📄 License
  203. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  204. **Copyright © 2025 Alireza Rezvani**
  205. ---
  206. ## 🙏 Acknowledgments
  207. - Built for the [Claude Code](https://claude.com/claude-code) community.
  208. - The behavioural-guardrail skill adapts the four principles from the MIT-licensed [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (inspired by Andrej Karpathy's commentary on LLM coding pitfalls). Original prose; attribution preserved in `skill/karpathy-guidelines/SKILL.md`.
  209. - Several plugin conventions (layered hook config, `Stop` audit hook, command discovery metadata, `paths:` scoping on skills, fail-closed contracts) are adapted from the MIT-licensed [shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice). Patterns implemented in original code with attribution in `CHANGELOG.md`.
  210. - Anthropic's [Claude Code documentation](https://code.claude.com/docs/en/memory) drove the load-event integrations (`InstructionsLoaded`, all five `load_reason` matchers) and the `context: fork` task-style skills.
  211. ---
  212. ## 🚦 Project Status
  213. **Version:** 2.1.0 (see [CHANGELOG.md](CHANGELOG.md))
  214. **Status:** ✅ Stable & Production-Ready
  215. **Requires:** Claude Code 2.1.4+ for hooks/`InstructionsLoaded`/`paths:` features
  216. ---
  217. ## 📊 Quick Stats
  218. - **5** skills (`claudeforge-skill`, `karpathy-guidelines`, plus three forked audit skills)
  219. - **3** slash commands (`/enhance-claude-md`, `/sync-claude-md` with `--weekly`, `/claude-to-agents`)
  220. - **1** agent (`claude-md-guardian`, fail-closed contract)
  221. - **3** hook scripts wired across `PostToolUse`, `InstructionsLoaded`, `Stop`
  222. - **5** Python modules under `skill/` (analyzer, validator, generator, template_selector, workflow)
  223. - **7** reference CLAUDE.md templates under `skill/examples/`
  224. - **150** — hard line cap per CLAUDE.md, enforced at load time *and* write time
  225. ---
  226. ## 🌟 Star History
  227. If you find ClaudeForge helpful, please consider giving it a star on GitHub!
  228. [![Star History Chart](https://api.star-history.com/svg?repos=alirezarezvani/ClaudeForge&type=Date)](https://star-history.com/#alirezarezvani/ClaudeForge&Date)
  229. ---
  230. <div align="center">
  231. **[⬆ Back to Top](#claudeforge)**
  232. Made with ❤️ for the Claude Code community
  233. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

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