claudeforge-cli 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +431 -0
- package/bin/cli.js +155 -0
- package/package.json +43 -0
- package/src/commands/add.js +205 -0
- package/src/commands/create.js +218 -0
- package/src/commands/github.js +479 -0
- package/src/commands/init.js +107 -0
- package/src/commands/project.js +123 -0
- package/src/commands/status.js +183 -0
- package/src/commands/upgrade.js +114 -0
- package/src/index.js +6 -0
- package/src/logger.js +90 -0
- package/src/scaffolder.js +45 -0
- package/src/stack-detector.js +62 -0
- package/templates/.env.example.tpl +21 -0
- package/templates/.gitignore.tpl +40 -0
- package/templates/CLAUDE.local.md.tpl +32 -0
- package/templates/CLAUDE.md.tpl +112 -0
- package/templates/claude/README.md.tpl +94 -0
- package/templates/claude/agents/code-reviewer.md.tpl +142 -0
- package/templates/claude/commands/commit.md.tpl +34 -0
- package/templates/claude/commands/explain-codebase.md.tpl +37 -0
- package/templates/claude/commands/fix-issue.md.tpl +43 -0
- package/templates/claude/commands/memory-sync.md.tpl +49 -0
- package/templates/claude/commands/project-health.md.tpl +70 -0
- package/templates/claude/commands/review-pr.md.tpl +43 -0
- package/templates/claude/commands/scaffold-structure.md.tpl +308 -0
- package/templates/claude/commands/setup-project.md.tpl +253 -0
- package/templates/claude/commands/standup.md.tpl +34 -0
- package/templates/claude/hooks/post-tool-use.sh.tpl +44 -0
- package/templates/claude/hooks/pre-tool-use.sh.tpl +64 -0
- package/templates/claude/rules/no-sensitive-files.md.tpl +29 -0
- package/templates/claude/settings.json.tpl +50 -0
- package/templates/claude/settings.local.json.tpl +4 -0
- package/templates/claude/skills/project-conventions/SKILL.md.tpl +39 -0
- package/templates/mcp.json.tpl +9 -0
- package/templates/memory/MEMORY.md.tpl +37 -0
- package/templates/memory/feedback_communication.md.tpl +29 -0
- package/templates/memory/project_ai_workflow.md.tpl +43 -0
- package/templates/memory/user_profile.md.tpl +30 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Vaibhav Jain
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,431 @@
|
|
|
1
|
+
# claudeforge
|
|
2
|
+
|
|
3
|
+
> Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/claudeforge)
|
|
6
|
+
[](https://pypi.org/project/claudeforge)
|
|
7
|
+
[](LICENSE)
|
|
8
|
+
[](https://nodejs.org)
|
|
9
|
+
[](https://python.org)
|
|
10
|
+
|
|
11
|
+
**No API key required.** Works with any Claude model — GitHub Copilot, Claude.ai, or any IDE with the Claude Code extension.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Table of Contents
|
|
16
|
+
|
|
17
|
+
- [What It Does](#what-it-does)
|
|
18
|
+
- [Install](#install)
|
|
19
|
+
- [Quick Start](#quick-start)
|
|
20
|
+
- [CLI Commands](#cli-commands)
|
|
21
|
+
- [create](#create--interactive-wizard)
|
|
22
|
+
- [init](#init--scaffold-project-structure)
|
|
23
|
+
- [project](#project--prepare-ai-context)
|
|
24
|
+
- [add](#add--scaffold-agents-commands-skills)
|
|
25
|
+
- [github](#github--cicd--devcontainer)
|
|
26
|
+
- [status](#status--show-whats-configured)
|
|
27
|
+
- [upgrade](#upgrade--update-built-in-templates)
|
|
28
|
+
- [Slash Commands (in IDE chat)](#slash-commands-in-ide-chat)
|
|
29
|
+
- [What Gets Scaffolded](#what-gets-scaffolded)
|
|
30
|
+
- [How It Works](#how-it-works)
|
|
31
|
+
- [Troubleshooting](#troubleshooting)
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## What It Does
|
|
36
|
+
|
|
37
|
+
`claudeforge` gives you a production-ready Claude Code setup:
|
|
38
|
+
|
|
39
|
+
- **Interactive wizard** (`create`) — go from zero to a fully configured project in one command
|
|
40
|
+
- **9 slash commands** for your daily workflow — `/setup-project`, `/commit`, `/review-pr`, `/scaffold-structure`, `/standup`, `/fix-issue`, `/explain-codebase`, `/project-health`, `/memory-sync`
|
|
41
|
+
- **A thorough code-reviewer agent** that checks correctness, security, performance, test coverage, style, and documentation
|
|
42
|
+
- **GitHub Actions CI/CD** auto-generated for your stack (Node, Python, Go, Rust)
|
|
43
|
+
- **VS Code devcontainer** with the Claude Code extension pre-configured
|
|
44
|
+
- **Hook scripts** that block dangerous operations before they run
|
|
45
|
+
- **A memory system** that persists project context across every Claude session
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## Install
|
|
50
|
+
|
|
51
|
+
### via npm (recommended)
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install -g claudeforge
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### via pip
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pip install claudeforge
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
> **pip users:** Node.js 18+ must be on your PATH. The pip package delegates to the Node.js CLI automatically.
|
|
64
|
+
|
|
65
|
+
Verify installation:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
claudeforge --version
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Quick Start
|
|
74
|
+
|
|
75
|
+
### Option A — Interactive wizard (fastest)
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
claudeforge create my-api
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Walks you through project name, description, stack, and optional features (CI/CD, devcontainer, Docker). Then runs everything automatically.
|
|
82
|
+
|
|
83
|
+
### Option B — Manual setup
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
# 1. Go to your project directory
|
|
87
|
+
cd my-project
|
|
88
|
+
|
|
89
|
+
# 2. Scaffold the Claude Code structure
|
|
90
|
+
claudeforge init
|
|
91
|
+
|
|
92
|
+
# 3. Generate CI/CD and devcontainer
|
|
93
|
+
claudeforge github
|
|
94
|
+
|
|
95
|
+
# 4. Prepare AI context (detects your tech stack automatically)
|
|
96
|
+
claudeforge project "FastAPI REST API with PostgreSQL and Redis"
|
|
97
|
+
|
|
98
|
+
# 5. Open the project in VS Code / JetBrains / any IDE with Claude Code
|
|
99
|
+
# 6. In the Claude Code chat window, run:
|
|
100
|
+
# /setup-project "FastAPI REST API with PostgreSQL and Redis"
|
|
101
|
+
|
|
102
|
+
# Claude will fill in CLAUDE.md, settings, agents, commands, and memory
|
|
103
|
+
# tailored to your exact stack — no manual editing required.
|
|
104
|
+
|
|
105
|
+
# 7. Then run:
|
|
106
|
+
# /scaffold-structure
|
|
107
|
+
# to create src/, tests/, and starter files for your stack.
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## CLI Commands
|
|
113
|
+
|
|
114
|
+
### `create` — Interactive wizard
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
claudeforge create my-api
|
|
118
|
+
claudeforge create # prompts for name
|
|
119
|
+
claudeforge create --dir ~/Projects
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Walks you through:
|
|
123
|
+
|
|
124
|
+
1. Project name
|
|
125
|
+
2. Description (used by Claude to AI-configure everything)
|
|
126
|
+
3. Tech stack selection
|
|
127
|
+
4. Optional features: GitHub Actions CI/CD, devcontainer, Docker files
|
|
128
|
+
|
|
129
|
+
Then runs `init`, `project`, and `github` automatically — one command from zero to fully configured.
|
|
130
|
+
|
|
131
|
+
---
|
|
132
|
+
|
|
133
|
+
### `init` — Scaffold project structure
|
|
134
|
+
|
|
135
|
+
```bash
|
|
136
|
+
claudeforge init
|
|
137
|
+
claudeforge init --dir ./my-project
|
|
138
|
+
claudeforge init --dry-run # preview without writing
|
|
139
|
+
claudeforge init --force # overwrite existing files
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Creates 25 files across the full Claude Code structure. Run this once per project.
|
|
143
|
+
|
|
144
|
+
**What gets created:**
|
|
145
|
+
|
|
146
|
+
| Path | Purpose |
|
|
147
|
+
|------|---------|
|
|
148
|
+
| `.claude/settings.json` | Team-shared permissions, model, hooks |
|
|
149
|
+
| `.claude/settings.local.json` | Personal overrides (gitignored) |
|
|
150
|
+
| `.claude/agents/code-reviewer.md` | 7-category code review agent |
|
|
151
|
+
| `.claude/commands/` | 9 slash commands (see below) |
|
|
152
|
+
| `.claude/hooks/pre-tool-use.sh` | Blocks rm -rf, curl\|bash, .env edits |
|
|
153
|
+
| `.claude/hooks/post-tool-use.sh` | Reminds to run tests after edits |
|
|
154
|
+
| `.claude/rules/no-sensitive-files.md` | Rule: don't touch secrets |
|
|
155
|
+
| `.claude/skills/project-conventions/` | Style skill loaded before writing code |
|
|
156
|
+
| `memory/MEMORY.md` | Index — always loaded by Claude |
|
|
157
|
+
| `memory/user_profile.md` | Your role and preferences (gitignored) |
|
|
158
|
+
| `memory/feedback_communication.md` | How Claude should behave |
|
|
159
|
+
| `memory/project_ai_workflow.md` | AI conventions for this project |
|
|
160
|
+
| `CLAUDE.md` | Project context template |
|
|
161
|
+
| `CLAUDE.local.md` | Personal context (gitignored) |
|
|
162
|
+
| `.mcp.json` | MCP servers (context7 pre-configured) |
|
|
163
|
+
| `.env.example` | Environment variable documentation |
|
|
164
|
+
| `.gitignore` | Covers secrets, local settings, OS artifacts |
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
### `project` — Prepare AI context
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
claudeforge project "describe your project in plain English"
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
Detects your tech stack from existing files (`package.json`, `go.mod`, `requirements.txt`, etc.), writes a `SETUP_CONTEXT.md` with full context, and tells you the exact command to run in Claude Code chat.
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
# Examples
|
|
178
|
+
claudeforge project "Next.js SaaS with Stripe, Prisma, and Clerk auth"
|
|
179
|
+
claudeforge project "Go gRPC microservice with PostgreSQL and Redis cache"
|
|
180
|
+
claudeforge project "Django REST API with Celery, RabbitMQ, and S3"
|
|
181
|
+
claudeforge project "Rust CLI tool for parsing and transforming CSV files"
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
After running, open Claude Code and run `/setup-project "your description"` in chat.
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
### `add` — Scaffold agents, commands, skills
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
# Add a specialized agent
|
|
192
|
+
claudeforge add agent <name> [--description "..."] [--model sonnet|opus|haiku] [--color blue]
|
|
193
|
+
|
|
194
|
+
# Add a slash command
|
|
195
|
+
claudeforge add command <name> [--description "..."]
|
|
196
|
+
|
|
197
|
+
# Add a skill
|
|
198
|
+
claudeforge add skill <name> [--description "..."] [--no-user-invocable]
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
# Real examples
|
|
203
|
+
claudeforge add agent sql-reviewer \
|
|
204
|
+
--description "Reviews SQL migrations for safety, performance, and rollback safety"
|
|
205
|
+
|
|
206
|
+
claudeforge add command deploy \
|
|
207
|
+
--description "Run pre-deploy checks, deploy to staging, run smoke tests"
|
|
208
|
+
|
|
209
|
+
claudeforge add skill api-conventions \
|
|
210
|
+
--description "Apply REST API naming and response conventions before writing endpoints"
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
| Flag | Description |
|
|
214
|
+
|------|-------------|
|
|
215
|
+
| `--description <text>` | Frontmatter description (important — determines when Claude invokes it) |
|
|
216
|
+
| `-f, --force` | Overwrite if file already exists |
|
|
217
|
+
| `-d, --dir <path>` | Target directory |
|
|
218
|
+
| `--model <model>` | (agent only) model override |
|
|
219
|
+
| `--color <color>` | (agent only) color in Claude UI |
|
|
220
|
+
| `--no-user-invocable` | (skill only) Claude-only, not user-invocable |
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
### `github` — CI/CD & devcontainer
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
claudeforge github
|
|
228
|
+
claudeforge github --dry-run # preview without writing
|
|
229
|
+
claudeforge github --stack python # force stack detection
|
|
230
|
+
claudeforge github --no-devcontainer # skip devcontainer
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Auto-detects your stack and generates:
|
|
234
|
+
|
|
235
|
+
| Path | Purpose |
|
|
236
|
+
|------|---------|
|
|
237
|
+
| `.github/workflows/ci.yml` | Lint, test, build on push/PR |
|
|
238
|
+
| `.github/pull_request_template.md` | Structured PR checklist |
|
|
239
|
+
| `.github/ISSUE_TEMPLATE/bug_report.md` | Bug report template |
|
|
240
|
+
| `.github/ISSUE_TEMPLATE/feature_request.md` | Feature request template |
|
|
241
|
+
| `.github/CODEOWNERS` | Ownership file |
|
|
242
|
+
| `.devcontainer/devcontainer.json` | VS Code devcontainer with Claude Code |
|
|
243
|
+
|
|
244
|
+
CI workflows are generated for: **Node.js**, **Python**, **Go**, **Rust**, and **generic**.
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
### `status` — Show what's configured
|
|
249
|
+
|
|
250
|
+
```bash
|
|
251
|
+
claudeforge status
|
|
252
|
+
claudeforge status --dir ./my-project
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
Prints a full summary:
|
|
256
|
+
|
|
257
|
+
```
|
|
258
|
+
Core Files ✓ 8/8 present
|
|
259
|
+
Settings Model: claude-sonnet-4-6 | 13 allowed, 4 denied | 2 hooks
|
|
260
|
+
MCP Servers context7, postgres
|
|
261
|
+
Agents (3) code-reviewer, api-reviewer, db-reviewer
|
|
262
|
+
Slash Commands 9 commands configured
|
|
263
|
+
Skills (2) project-conventions, api-conventions
|
|
264
|
+
Memory (4 files) ● 3 filled ○ 1 empty template
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
### `upgrade` — Update built-in templates
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
claudeforge upgrade # update hooks, rules, built-in commands
|
|
273
|
+
claudeforge upgrade --dry-run # preview changes
|
|
274
|
+
claudeforge upgrade --all # also update CLAUDE.md, settings.json, agents (⚠ overwrites edits)
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
By default, only **infrastructure files** are updated (hook scripts, rules, built-in slash commands). Your edited files (`CLAUDE.md`, `settings.json`, custom agents) are untouched.
|
|
278
|
+
|
|
279
|
+
---
|
|
280
|
+
|
|
281
|
+
## Slash Commands (in IDE chat)
|
|
282
|
+
|
|
283
|
+
Run these in the Claude Code chat window in VS Code, JetBrains, or any Claude Code IDE. Works with any Claude model — no separate API key.
|
|
284
|
+
|
|
285
|
+
### Setup & Maintenance
|
|
286
|
+
|
|
287
|
+
| Command | When to run | What it does |
|
|
288
|
+
|---------|-------------|-------------|
|
|
289
|
+
| `/setup-project "description"` | After `claudeforge init` | Fills in CLAUDE.md, settings, .env.example, .mcp.json, memory, generates 2–4 project-specific agents and commands, then documents every file it creates |
|
|
290
|
+
| `/scaffold-structure` | After `/setup-project` | Creates the actual `src/`, `tests/`, `cmd/` directory structure with real starter files for your stack |
|
|
291
|
+
| `/project-health` | Weekly / after big changes | Audits your setup: checks CLAUDE.md completeness, hook coverage, memory fill level, and gives prioritized improvement suggestions |
|
|
292
|
+
| `/memory-sync` | End of work session | Reviews the session and updates `memory/` files with preferences, decisions, and project context |
|
|
293
|
+
|
|
294
|
+
### Daily Development
|
|
295
|
+
|
|
296
|
+
| Command | When to run | What it does |
|
|
297
|
+
|---------|-------------|-------------|
|
|
298
|
+
| `/commit` | After completing a feature | Reads `git diff`, stages relevant files, writes a conventional commit message |
|
|
299
|
+
| `/review-pr` | Before opening a PR | Reviews the branch diff — correctness, security, tests, style — with severity ratings |
|
|
300
|
+
| `/fix-issue "error message"` | When something breaks | Locates the bug, forms a hypothesis, makes a minimal targeted fix, verifies with tests |
|
|
301
|
+
| `/standup ["last 3 days"]` | Morning standup | Generates a concise update from recent git commits and open PRs |
|
|
302
|
+
| `/explain-codebase ["area"]` | Onboarding / exploring | Explains architecture, key flows, and what to read first |
|
|
303
|
+
|
|
304
|
+
---
|
|
305
|
+
|
|
306
|
+
## What Gets Scaffolded
|
|
307
|
+
|
|
308
|
+
### `code-reviewer` Agent (7 categories)
|
|
309
|
+
|
|
310
|
+
Reviews changed code across:
|
|
311
|
+
1. **Correctness** — logic errors, edge cases, async issues
|
|
312
|
+
2. **Security** — hardcoded secrets, injection, path traversal, SSRF
|
|
313
|
+
3. **Error Handling** — swallowed errors, missing timeouts, resource leaks
|
|
314
|
+
4. **Performance** — N+1 queries, unbounded growth, blocking calls
|
|
315
|
+
5. **Test Coverage** — happy path, error paths, edge cases, assertions
|
|
316
|
+
6. **Style** — naming, magic numbers, dead code, DRY
|
|
317
|
+
7. **Documentation** — missing docstrings, stale docs, changelog
|
|
318
|
+
|
|
319
|
+
Returns: `✓ LGTM` / `~ LGTM with suggestions` / `⚠ Address warnings` / `✗ Needs changes`
|
|
320
|
+
|
|
321
|
+
### Hook Scripts (auto-`chmod 755`)
|
|
322
|
+
|
|
323
|
+
**`pre-tool-use.sh`** blocks before every tool call:
|
|
324
|
+
- `rm -rf` on absolute paths outside `/tmp`
|
|
325
|
+
- Editing `.env`, credentials, key files (warns first)
|
|
326
|
+
- `curl | bash` and `wget | sh` patterns
|
|
327
|
+
|
|
328
|
+
**`post-tool-use.sh`** injects reminders:
|
|
329
|
+
- Prompts to run tests after editing test files
|
|
330
|
+
|
|
331
|
+
### Memory System
|
|
332
|
+
|
|
333
|
+
Four structured memory files — Claude reads them every session:
|
|
334
|
+
|
|
335
|
+
| File | What it stores | Gitignored? |
|
|
336
|
+
|------|---------------|-------------|
|
|
337
|
+
| `MEMORY.md` | Index of all memory files | No |
|
|
338
|
+
| `user_profile.md` | Your role, background, preferences | Yes |
|
|
339
|
+
| `feedback_communication.md` | How Claude should behave | No |
|
|
340
|
+
| `project_ai_workflow.md` | AI conventions for this project | No |
|
|
341
|
+
|
|
342
|
+
---
|
|
343
|
+
|
|
344
|
+
## How It Works
|
|
345
|
+
|
|
346
|
+
```
|
|
347
|
+
┌─────────────────────────────┐ ┌──────────────────────────────┐
|
|
348
|
+
│ Terminal CLI │ │ Claude Code (IDE chat) │
|
|
349
|
+
│ │ │ │
|
|
350
|
+
│ create my-api ────────────┼─────┼▶ init + project + github │
|
|
351
|
+
│ │ │ │
|
|
352
|
+
│ init ────────────┼─────┼▶ .claude/ structure created │
|
|
353
|
+
│ project "..." ────────────┼─────┼▶ SETUP_CONTEXT.md written │
|
|
354
|
+
│ github ────────────┼─────┼▶ CI/CD + devcontainer │
|
|
355
|
+
│ │ │ │
|
|
356
|
+
│ │◀────┼─ /setup-project "..." │
|
|
357
|
+
│ │ │ ↳ fills CLAUDE.md │
|
|
358
|
+
│ │ │ ↳ updates settings.json │
|
|
359
|
+
│ │ │ ↳ creates agents │
|
|
360
|
+
│ │ │ ↳ creates commands │
|
|
361
|
+
│ │ │ ↳ documents every file │
|
|
362
|
+
│ │ │ │
|
|
363
|
+
│ │◀────┼─ /scaffold-structure │
|
|
364
|
+
│ │ │ ↳ creates src/, tests/ │
|
|
365
|
+
│ │ │ ↳ writes starter files │
|
|
366
|
+
│ │ │ │
|
|
367
|
+
│ add agent ... ────────────┼─────┼▶ template created │
|
|
368
|
+
│ status ────────────┼─────┼▶ summary printed │
|
|
369
|
+
│ upgrade ────────────┼─────┼▶ hooks/rules updated │
|
|
370
|
+
└─────────────────────────────┘ └──────────────────────────────┘
|
|
371
|
+
```
|
|
372
|
+
|
|
373
|
+
The CLI handles file scaffolding. The AI work happens inside the IDE where Claude has full tool access to read, write, and run commands — no separate API key needed.
|
|
374
|
+
|
|
375
|
+
---
|
|
376
|
+
|
|
377
|
+
## Troubleshooting
|
|
378
|
+
|
|
379
|
+
**`claudeforge: command not found`**
|
|
380
|
+
```bash
|
|
381
|
+
# npm
|
|
382
|
+
npm install -g claudeforge
|
|
383
|
+
# pip (ensure ~/.local/bin is on PATH)
|
|
384
|
+
pip install claudeforge
|
|
385
|
+
export PATH="$HOME/.local/bin:$PATH"
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
**pip install: `Node.js is required`**
|
|
389
|
+
```bash
|
|
390
|
+
# macOS
|
|
391
|
+
brew install node
|
|
392
|
+
# Ubuntu/Debian
|
|
393
|
+
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
|
394
|
+
sudo apt-get install -y nodejs
|
|
395
|
+
```
|
|
396
|
+
|
|
397
|
+
**`/setup-project` didn't generate anything**
|
|
398
|
+
Make sure you ran `claudeforge init` first — the `.claude/commands/` directory must exist for slash commands to work.
|
|
399
|
+
|
|
400
|
+
**Hook scripts not running**
|
|
401
|
+
```bash
|
|
402
|
+
# Verify hooks are executable
|
|
403
|
+
ls -la .claude/hooks/
|
|
404
|
+
# Re-apply execute permission
|
|
405
|
+
chmod 755 .claude/hooks/*.sh
|
|
406
|
+
# Re-run init to restore hooks
|
|
407
|
+
claudeforge init --force
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
**`claudeforge upgrade` overwrote my custom changes**
|
|
411
|
+
Only use `--all` flag when you want to reset user-owned files. Without `--all`, only infrastructure files (hooks, rules, built-in commands) are updated.
|
|
412
|
+
|
|
413
|
+
**Slash commands not showing in IDE**
|
|
414
|
+
Confirm you're running Claude Code (not just Copilot Chat). The `.claude/commands/` directory must be in the project root. Restart the IDE after running `init`.
|
|
415
|
+
|
|
416
|
+
---
|
|
417
|
+
|
|
418
|
+
## Requirements
|
|
419
|
+
|
|
420
|
+
| Requirement | Version | Notes |
|
|
421
|
+
|-------------|---------|-------|
|
|
422
|
+
| Node.js | 18+ | Required for the CLI |
|
|
423
|
+
| npm | any | Included with Node.js |
|
|
424
|
+
| Python | 3.8+ | Only if installing via pip |
|
|
425
|
+
| Claude Code | latest | IDE extension for slash commands |
|
|
426
|
+
|
|
427
|
+
---
|
|
428
|
+
|
|
429
|
+
## License
|
|
430
|
+
|
|
431
|
+
MIT
|
package/bin/cli.js
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
'use strict';
|
|
3
|
+
|
|
4
|
+
const { program } = require('commander');
|
|
5
|
+
const { version } = require('../package.json');
|
|
6
|
+
const initCommand = require('../src/commands/init');
|
|
7
|
+
const projectCommand = require('../src/commands/project');
|
|
8
|
+
const { addAgent, addCommand, addSkill } = require('../src/commands/add');
|
|
9
|
+
const statusCommand = require('../src/commands/status');
|
|
10
|
+
const upgradeCommand = require('../src/commands/upgrade');
|
|
11
|
+
const createCommand = require('../src/commands/create');
|
|
12
|
+
const githubCommand = require('../src/commands/github');
|
|
13
|
+
|
|
14
|
+
program
|
|
15
|
+
.name('claudeforge')
|
|
16
|
+
.description('Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command')
|
|
17
|
+
.version(version);
|
|
18
|
+
|
|
19
|
+
// ── init ─────────────────────────────────────────────────────────────────────
|
|
20
|
+
program
|
|
21
|
+
.command('init')
|
|
22
|
+
.description('Scaffold the Claude Code project structure (.claude/, memory/, CLAUDE.md, etc.)')
|
|
23
|
+
.option('-f, --force', 'Overwrite existing files without prompting')
|
|
24
|
+
.option('-n, --dry-run', 'Preview what would be created without writing anything')
|
|
25
|
+
.option('-d, --dir <path>', 'Target directory (defaults to current directory)')
|
|
26
|
+
.action(initCommand);
|
|
27
|
+
|
|
28
|
+
// ── project ───────────────────────────────────────────────────────────────────
|
|
29
|
+
program
|
|
30
|
+
.command('project <description>')
|
|
31
|
+
.description('Prepare your project for AI setup — writes SETUP_CONTEXT.md and guides you to run /setup-project in the Claude Code chat')
|
|
32
|
+
.option('-d, --dir <path>', 'Target directory (defaults to current directory)')
|
|
33
|
+
.addHelpText('after', `
|
|
34
|
+
No API key required. Works with any Claude model you already have access to
|
|
35
|
+
(GitHub Copilot, Claude.ai, or any IDE with the Claude Code extension).
|
|
36
|
+
|
|
37
|
+
Examples:
|
|
38
|
+
$ claudeforge project "FastAPI REST API with PostgreSQL and Redis"
|
|
39
|
+
$ claudeforge project "React + Tailwind dashboard with Supabase and Stripe"
|
|
40
|
+
$ claudeforge project "Go microservice for payment processing" --dir ./my-service
|
|
41
|
+
|
|
42
|
+
After running this, open the project in your IDE and run:
|
|
43
|
+
/setup-project "your description"
|
|
44
|
+
in the Claude Code chat window.
|
|
45
|
+
`)
|
|
46
|
+
.action(projectCommand);
|
|
47
|
+
|
|
48
|
+
// ── add ──────────────────────────────────────────────────────────────────────
|
|
49
|
+
const addCmd = program
|
|
50
|
+
.command('add')
|
|
51
|
+
.description('Scaffold a new agent, slash command, or skill');
|
|
52
|
+
|
|
53
|
+
addCmd
|
|
54
|
+
.command('agent <name>')
|
|
55
|
+
.description('Create a new sub-agent in .claude/agents/')
|
|
56
|
+
.option('-d, --dir <path>', 'Target directory')
|
|
57
|
+
.option('-f, --force', 'Overwrite if already exists')
|
|
58
|
+
.option('--description <text>', 'Agent description (shown in frontmatter)')
|
|
59
|
+
.option('--model <model>', 'Agent model: sonnet | opus | haiku', 'sonnet')
|
|
60
|
+
.option('--color <color>', 'Agent color in Claude UI', 'blue')
|
|
61
|
+
.addHelpText('after', `
|
|
62
|
+
Example:
|
|
63
|
+
$ claudeforge add agent sql-reviewer --description "Reviews SQL migrations for safety"
|
|
64
|
+
`)
|
|
65
|
+
.action(addAgent);
|
|
66
|
+
|
|
67
|
+
addCmd
|
|
68
|
+
.command('command <name>')
|
|
69
|
+
.description('Create a new slash command in .claude/commands/')
|
|
70
|
+
.option('-d, --dir <path>', 'Target directory')
|
|
71
|
+
.option('-f, --force', 'Overwrite if already exists')
|
|
72
|
+
.option('--description <text>', 'Command description (shown in command palette)')
|
|
73
|
+
.addHelpText('after', `
|
|
74
|
+
Example:
|
|
75
|
+
$ claudeforge add command deploy --description "Deploy the app to staging"
|
|
76
|
+
`)
|
|
77
|
+
.action(addCommand);
|
|
78
|
+
|
|
79
|
+
addCmd
|
|
80
|
+
.command('skill <name>')
|
|
81
|
+
.description('Create a new skill in .claude/skills/<name>/SKILL.md')
|
|
82
|
+
.option('-d, --dir <path>', 'Target directory')
|
|
83
|
+
.option('-f, --force', 'Overwrite if already exists')
|
|
84
|
+
.option('--description <text>', 'Skill trigger description')
|
|
85
|
+
.option('--no-user-invocable', 'Make this a Claude-only skill (user-invocable: false)')
|
|
86
|
+
.addHelpText('after', `
|
|
87
|
+
Example:
|
|
88
|
+
$ claudeforge add skill api-conventions --description "Apply REST API naming conventions"
|
|
89
|
+
`)
|
|
90
|
+
.action(addSkill);
|
|
91
|
+
|
|
92
|
+
// ── status ────────────────────────────────────────────────────────────────────
|
|
93
|
+
program
|
|
94
|
+
.command('status')
|
|
95
|
+
.description('Show what is configured in this Claude Code project')
|
|
96
|
+
.option('-d, --dir <path>', 'Target directory (defaults to current directory)')
|
|
97
|
+
.action(statusCommand);
|
|
98
|
+
|
|
99
|
+
// ── upgrade ───────────────────────────────────────────────────────────────────
|
|
100
|
+
program
|
|
101
|
+
.command('upgrade')
|
|
102
|
+
.description('Update infrastructure templates (hooks, rules, skills) to the latest version')
|
|
103
|
+
.option('-d, --dir <path>', 'Target directory (defaults to current directory)')
|
|
104
|
+
.option('-n, --dry-run', 'Preview what would change without writing anything')
|
|
105
|
+
.option('--all', 'Also update user-owned files (CLAUDE.md, settings.json, agents, commands) — WILL overwrite your edits')
|
|
106
|
+
.addHelpText('after', `
|
|
107
|
+
By default, only infrastructure files are updated:
|
|
108
|
+
.claude/hooks/*, .claude/rules/*, .claude/skills/project-conventions/*, memory/MEMORY.md
|
|
109
|
+
|
|
110
|
+
User-owned files (CLAUDE.md, .claude/settings.json, agents, commands, .mcp.json) are left untouched
|
|
111
|
+
unless you pass --all.
|
|
112
|
+
`)
|
|
113
|
+
.action(upgradeCommand);
|
|
114
|
+
|
|
115
|
+
// ── create ────────────────────────────────────────────────────────────────────
|
|
116
|
+
program
|
|
117
|
+
.command('create [name]')
|
|
118
|
+
.description('Interactive wizard — scaffold a new AI-powered project from scratch')
|
|
119
|
+
.option('-d, --dir <path>', 'Parent directory to create the project in (defaults to current directory)')
|
|
120
|
+
.addHelpText('after', `
|
|
121
|
+
Walks you through project name, description, stack selection, and optional
|
|
122
|
+
features (CI/CD, devcontainer, GitHub templates). Then runs init + project
|
|
123
|
+
automatically — one command to go from zero to a fully configured Claude project.
|
|
124
|
+
|
|
125
|
+
Example:
|
|
126
|
+
$ claudeforge create my-api
|
|
127
|
+
$ claudeforge create # prompts for name
|
|
128
|
+
`)
|
|
129
|
+
.action(createCommand);
|
|
130
|
+
|
|
131
|
+
// ── github ────────────────────────────────────────────────────────────────────
|
|
132
|
+
program
|
|
133
|
+
.command('github')
|
|
134
|
+
.description('Generate GitHub Actions CI/CD, PR templates, issue templates, and devcontainer')
|
|
135
|
+
.option('-d, --dir <path>', 'Target directory (defaults to current directory)')
|
|
136
|
+
.option('-n, --dry-run', 'Preview what would be created without writing anything')
|
|
137
|
+
.option('--stack <stack>', 'Force a stack: node | python | go | rust | generic')
|
|
138
|
+
.option('--no-devcontainer', 'Skip .devcontainer/ generation')
|
|
139
|
+
.option('--no-pr-template', 'Skip pull_request_template.md')
|
|
140
|
+
.option('--no-issue-templates','Skip issue templates')
|
|
141
|
+
.addHelpText('after', `
|
|
142
|
+
Auto-detects your stack and generates:
|
|
143
|
+
.github/workflows/ci.yml — lint, test, build on push/PR
|
|
144
|
+
.github/pull_request_template.md — structured PR checklist
|
|
145
|
+
.github/ISSUE_TEMPLATE/ — bug report + feature request templates
|
|
146
|
+
.github/CODEOWNERS — ownership file (placeholder)
|
|
147
|
+
.devcontainer/devcontainer.json — VS Code devcontainer with Claude Code
|
|
148
|
+
|
|
149
|
+
Examples:
|
|
150
|
+
$ claudeforge github
|
|
151
|
+
$ claudeforge github --stack python --no-devcontainer
|
|
152
|
+
`)
|
|
153
|
+
.action(githubCommand);
|
|
154
|
+
|
|
155
|
+
program.parse(process.argv);
|
package/package.json
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "claudeforge-cli",
|
|
3
|
+
"version": "1.0.0",
|
|
4
|
+
"description": "Forge production-ready AI agent projects — agents, slash commands, memory, CI/CD, and devcontainers in one command",
|
|
5
|
+
"bin": {
|
|
6
|
+
"claudeforge": "bin/cli.js"
|
|
7
|
+
},
|
|
8
|
+
"main": "./src/index.js",
|
|
9
|
+
"files": [
|
|
10
|
+
"bin/",
|
|
11
|
+
"src/",
|
|
12
|
+
"templates/",
|
|
13
|
+
"README.md"
|
|
14
|
+
],
|
|
15
|
+
"scripts": {
|
|
16
|
+
"test": "node --test src/**/*.test.js",
|
|
17
|
+
"link": "npm link",
|
|
18
|
+
"start": "node bin/cli.js"
|
|
19
|
+
},
|
|
20
|
+
"keywords": [
|
|
21
|
+
"claudeforge",
|
|
22
|
+
"claude",
|
|
23
|
+
"claude-code",
|
|
24
|
+
"anthropic",
|
|
25
|
+
"scaffold",
|
|
26
|
+
"ai",
|
|
27
|
+
"agents",
|
|
28
|
+
"cli",
|
|
29
|
+
"boilerplate",
|
|
30
|
+
"devcontainer",
|
|
31
|
+
"github-actions"
|
|
32
|
+
],
|
|
33
|
+
"author": "Vaibhav Jain",
|
|
34
|
+
"license": "MIT",
|
|
35
|
+
"engines": {
|
|
36
|
+
"node": ">=18.0.0"
|
|
37
|
+
},
|
|
38
|
+
"dependencies": {
|
|
39
|
+
"chalk": "4.1.2",
|
|
40
|
+
"commander": "^12.1.0",
|
|
41
|
+
"fs-extra": "^11.2.0"
|
|
42
|
+
}
|
|
43
|
+
}
|