claude-code-up
CLAUDE.md1 starsChanged 6 months agoMITView on GitHub
Bias toward caution over speed. For trivial tasks, use judgment. claude-code-up (npm package claude-code-up, bin claude-code-up) is an interactive CLI that bootstraps a Claude Code project: it runs a funnel of prompts (category → language → framework → database → ORM), then writes .claude/, .mcp.json, CLAUDE.md, optional scaffolder output, and pushes to GitHub. The end-of-flow runs claude /init headless to verify wiring. It is project-scope only — never touches ~/.claude/. Anything user-scope is documented in STACK.md rather than auto-run. There…
- Reads credentials
In this repository17 other files it gives its agents.
- .claude/marketplaces/superpowers/AGENTS.mdAGENTS.md
- .claude/marketplaces/superpowers/CLAUDE.mdCLAUDE.md
- .claude/marketplaces/wshobson/CLAUDE.mdCLAUDE.md
- octo-issue-trackerSkill
- cavemanSkill
- improve-codebase-architectureSkill
- qaSkill
- zoom-outSkill
- scenario-testerSkill
- brainstormingSkill
- requesting-code-reviewSkill
- subagent-driven-developmentSkill
- systematic-debuggingSkill
- test-driven-developmentSkill
- using-git-worktreesSkill
- writing-plansSkill
- exampleSkill
The file
We split this CLAUDE.md into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 42
After editing any catalog/*.json, run npm run gen (the pre-hooks pick this up automatically for the standard scripts).
- Very specific: line 58
Project-scope only: No code should write to ~/.claude/.
- Very specific: line 72
Always pick a tier: default (always installed, no applyWhen), conditional (with applyWhen rules), or skip (requires reason).
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Behavioral guidelines
Bias toward caution over speed. For trivial tasks, use judgment.
- Think before coding. State assumptions explicitly; surface tradeoffs; ask when unclear. Don't pick silently between interpretations.
- Simplicity first. Minimum code that solves the problem. No speculative abstractions, configurability, or error handling for impossible scenarios.
- Surgical changes. Touch only what the task requires. Match existing style. Remove imports/vars your changes orphaned — don't delete pre-existing dead code unprompted.
- Goal-driven. Restate the task as a verifiable outcome before implementing. For multi-step work, write a brief plan with a verification step for each.
Project at a glance
claude-code-up (npm package claude-code-up, bin claude-code-up) is an interactive CLI that bootstraps a Claude Code project: it runs a funnel of prompts (category → language → framework → database → ORM), then writes .claude/, .mcp.json, CLAUDE.md, optional scaffolder output, and pushes to GitHub. The end-of-flow runs claude /init headless to verify wiring.
It is project-scope only — never touches ~/.claude/. Anything user-scope is documented in STACK.md rather than auto-run.
Commands
npm run gen # regenerate src/{catalog,templates}.gen.ts from catalog/*.json and src/scripts/*.sh
npm run dev # tsx src/cli.ts — run the CLI from source (runs `gen` first via predev)
npm run typecheck # tsc --noEmit (runs `gen` first via pretypecheck)
npm run build # tsup → dist/cli.js (runs `gen` first via prebuild)
npm test # the husky pre-commit hook runs this — currently no test suite is wired up, so the hook just calls `npm test` which exits with whatever npm's default behavior isThere is no lint script; Biome is the configured formatter/linter (biome.json, tab indent, double quotes) but it's not bound to a script — run npx biome check . or npx biome format --write . directly when needed.
Architecture: mechanism in TS, policy in JSON
The core invariant: the TypeScript code is generic, all data lives in catalog/*.json. Adding a new MCP / agent / skill / scaffolder is a JSON edit, not a TS change.
Code generation pipeline
catalog/*.json + src/scripts/*.sh → scripts/gen-templates.mjs → src/catalog.gen.ts + src/templates.gen.ts → imported through src/catalog/loader.ts.
- The
.gen.tsfiles are auto-generated — do not edit. They're checked in but regenerated on everydev/typecheck/buildvia npm pre-hooks. gen-templates.mjsalso validates the JSON: every item must have a tier (default/conditional/skip);skiprequires areason;defaultmust not haveapplyWhen;project-types.jsonmust beschemaVersion: "2".- After editing any
catalog/*.json, runnpm run gen(the pre-hooks pick this up automatically for the standard scripts).
Funnel → decision tree → installation
- Prompts (
src/prompts/) collect funnel answers, scaffolder choice, stack components, MCPs, command bundles. The custom tri-state multiselect (tristate-multiselect.ts) gives ● / ◐ / ○ with a D-key drill-down — it's built on@clack/core, not@clack/prompts. - Decision tree (
src/stack/decision-tree.ts) resolves each catalog source (wshobson/superpowers/pocock) against the funnel viamatchesApplyWhenandresolveForSource.applyWhensemantics:- Missing field → always matches (default-like).
{}empty object → opt-in only, never auto-matches.- With rules → all present sections must intersect with the funnel (AND across sections, OR within a section).
- Generators (
src/generators/) write the artifacts:claude-dir.tsbuilds.claude/,claude-md.tswritesCLAUDE.md(preserves existing if scaffolder/clone/merge ran),mcp.tswrites.mcp.json+.envand runs a real JSON-RPCinitialize+ optionaltools/callhandshake against each MCP server before reporting success. - Orchestrator:
src/commands/init.tsis the single entry point that wires preflight (Claude Code version check, install prompt) → prompts → confirm → generators → optionalclaude /initheadless run →claude doctoroffer → optional child shell.
Important behavior to preserve
- Scaffolder runs BEFORE
.claude/is written, in an empty target dir, because most scaffolders (Expo, Next, Vite…) refuse to run otherwise.init.tshandles both shapes: scaffolders that take.(cwd is target) and scaffolders with a{{name}}placeholder (cwd is parent, scaffolder creates the subdir). When a scaffolder ran,generateClaudeMd/generateGitignoreare called withpreserveExisting: true. - MCP handshake is end-to-end, not just config-writing. Failures are surfaced with the stage that failed (
tools/call query: connect ECONNREFUSED…). Missing env vars produceskipped, not silent success. - Project-scope only. No code should write to
~/.claude/. User-scope tools (claude-mem,cc-lens) get documented inSTACK.mdwith a copy-pasteable install line.
Adding catalog entries
The high-frequency edit. See CONTRIBUTING.md for full templates. Quick map:
| Adding… | Edit | After |
| MCP server | catalog/mcps.json + extend McpServerId in src/types.ts | npm run gen && npm run typecheck |
| Agent / skill (from a source) | catalog/items/<source>.json | npm run gen |
Bundled skill with inline .md | catalog/skills.json | npm run gen |
| Framework scaffolder | catalog/scaffolders.json | npm run gen |
| Command bundle (lib installs per stack branch) | catalog/command-bundles.json | npm run gen |
Always pick a tier: default (always installed, no applyWhen), conditional (with applyWhen rules), or skip (requires reason). The gen script throws if these rules are violated.
Misc
- Husky pre-commit runs
npm test. There's no test suite yet — keep this in mind before adding one, and update.husky/pre-commitaccordingly. - The bundled MCP server stub at
src/index.tsis unrelated to the CLI — it's a placeholder MCP server scaffold and is not wired into the build (tsup.config.tsonly bundlessrc/cli.ts). - Bumping the CLI version requires editing both
package.jsonand theVERSIONconstant insrc/cli.ts.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

