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.
# Add to your Claude Code skills
git clone https://github.com/alirezarezvani/ClaudeForgeLast scanned: 5/25/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-25T08:22:42.470Z",
"semgrepRan": false,
"npmAuditRan": true,
"pipAuditRan": true
}No comments yet. Be the first to share your thoughts!
Automated CLAUDE.md creation, enhancement, and maintenance for Claude Code projects
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.
.claude-plugin/plugin.json; install with /plugin marketplace add alirezarezvani/ClaudeForge && /plugin install claudeforgehooks/hooks.json on PostToolUse(Edit|Write) and InstructionsLoaded (every load_reason); larger projects spread content across chained sub-files via @path imports/sync-claude-md — walks every CLAUDE.md, prunes stale references, splits when over the cap, repairs root ↔ sub chains/sync-claude-md --weekly — orchestrates three forked task-style skills in parallel: claude-md-drift-audit, claude-md-link-check, claude-md-dependency-rescan~/.claude/skills/karpathy-guidelines/ skill scoped to code-file globsAGENTS.md / .cursorrules / .windsurfrules interop — /enhance-claude-md detects sibling instruction files and chains them via @-imports instead of overwritingCLAUDE.local.md personal tier — per-developer overrides exempt from the cap, gitignored automaticallyhooks/hooks-config.json (committed defaults) + hooks/hooks-config.local.json (gitignored) lets developers opt out per machineSessionStart, PreToolUse, PostToolUse, InstructionsLoaded, Stop (one-line drift summary at session end)model: haiku with a fail-closed contract (Skill-tool only, never auto-commits, aborts on missing validated output)👉 Upgrading from v1.x? See docs/MIGRATION_V2.md.
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.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.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].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].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]./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./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./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.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.hooks/hooks.json — wires PostToolUse(Write|Edit), InstructionsLoaded (all five load_reason values), and Stop events to scripts under hooks/.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.hooks/audit-claude-md.py — Stop hook; one-line CLAUDE.md health summary printed at session end (total tracked / over cap / near cap).hooks/hooks-config.json + hooks/hooks-config.local.json — layered config; per-developer overrides without forking the shipped manifest.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.
curl -fsSL https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.sh | bash
iwr https://raw.githubusercontent.com/alirezarezvani/ClaudeForge/main/install.ps1 -useb | iex
git clone https://github.com/alirezarezvani/ClaudeForge.git
cd ClaudeForge
./install.sh # or .\install.ps1 on Windows
After installation, restart Claude Code and run:
/enhance-claude-md
That's it! The command will:
/enhance-claude-md
# Claude explores your repository and responds:
#
# "Based on my exploration, here's what I discovered:
#
# 📦 Project Type: Full-Stack Application
# 🛠️ Tech Stack: TypeScript, React, Node.js, PostgreSQL, Docker
# 👥 Team Size: Small (5 developers)
# 🚀 Development Phase: MVP
#
# 📋 Recommended Structure:
# - Root CLAUDE.md (navigation hub, ~100 lines)
# - backend/CLAUDE.md (API guidelines, ~150 lines)
# - frontend/CLAUDE.md (React guidelines, ~175 lines)
#
# Would you like me to create these files?"
#
# You: "Yes"
#
# ✅ CLAUDE.md created (108 lines)
# ✅ backend/CLAUDE.md created (156 lines)
# ✅ frontend/CLAUDE.md created (182 lines)
/enhance-claude-md
# Claude analyzes your current CLAUDE.md:
#
# "Quality Score: 65/100
#
# Missing Sections:
# - Project Structure (ASCII diagram)
# - Setup & Installation
# - Architecture
#
# Would you like me to enhance your CLAUDE.md with these sections?"
#
# You: "Yes"
#
# ✅ CLAUDE.md enhanced (+2 sections, quality score: 65 → 88)
# You start a new Claude Code session
# Guardian agent automatically checks for changes
#
# ✅ CLAUDE.md updated:
# - Tech Stack: Added 2 dependencies (react-query, tailwindcss)
# - Project Structure: Updated diagram with new components/ directory
# - Setup & Installation: New environment variables
#
# Changes: 3 sections, 12 lines