repo-pattern

A clean Claude Code setup and migrator in one command.

repo-pattern initializes or migrates a project into an ECC or gstack Claude Code workspace with safe defaults, MCP profiles, and zero vendored runtime clutter.

Why use it?

• Start fast — generate .claude/, .mcp.json, and repo-pattern metadata.
• Stay clean — no local skills, commands, hooks, scripts, or duplicated templates by default.
• Use MCP profiles — choose minimal, web, backend, research, full, or custom.
• Explicit pipeline — choose ECC (default) or the upstream global gstack installer.
• Migrate safely — audit, cleanup, doctor, and setup --migrate are built in.

Install

Use directly with npx without installing:

npx repo-pattern setup --profile web --yes

Or install the CLI globally, then run repo-pattern:

npm install -g @negikirin/repo-pattern

Quick start

Interactive setup:

npx repo-pattern setup

Scriptable setup:

npx repo-pattern setup --profile web --setup-pipeline ecc --yes
npx repo-pattern setup --profile web --setup-pipeline gstack --yes
npx repo-pattern setup --profile web --setup-pipeline gstack --with-rules --yes
npx repo-pattern setup --profile web --setup-pipeline none --with-rules --yes

Pipeline scope is explicit:

• ecc (default) — project-scoped ECC.
• gstack — user-scoped/global gstack at ~/.claude/skills/gstack.
• both — project-scoped ECC plus user-scoped/global gstack.
• none — base project metadata only.

gstack requires Git and Bun v1.0+. When Bun is missing on Linux or macOS, setup downloads the official installer over TLS, validates it, and installs Bun automatically. On unsupported systems, install Bun manually before setup. Its upstream setup runs with --quiet --no-plan-tune-hooks, so automated setup does not show settings diffs or wait for hook confirmation.

ECC rules are independent of the ECC plugin. ecc and both install auto-detected packs by default; the interactive wizard can switch to manual packs or none. gstack and none prompt whether to install rules, while scriptable setup requires --with-rules. Managed packs live in .claude/rules/ecc/ and can work when ECC plugin setup reports manual installation is still required.

Migrate an existing project:

npx repo-pattern audit
npx repo-pattern setup --profile web --migrate --yes
npx repo-pattern doctor

Commands

| Command | Purpose | |----|----| | repo-pattern help | Show CLI help. | | repo-pattern setup | Initialize or migrate a Claude Code setup. | | repo-pattern audit | Inspect current Claude Code/ECC state. | | repo-pattern doctor | Validate the generated setup. | | repo-pattern mcp --profile web | Regenerate .mcp.json from an MCP profile. | | repo-pattern rules | Apply or refresh project-local ECC rules. | | repo-pattern cleanup | Archive old local Claude runtime surfaces. | | repo-pattern ecc | Run or attempt ECC setup manually. |

Common options:

--target /path/to/project  # default: current directory
--profile web              # default MCP profile
--setup-pipeline ecc        # ecc (default), gstack, both, or none
--with-rules               # install auto-detected .claude/rules/ecc on gstack or none
                            # ecc and both install auto-detected rules by default
--with-skill ui-ux-pro-max # optional UI/UX skill; requires Python 3.x
--with-skills nextjs-pattern,fastapi-pattern # optional framework pattern skills
--migrate                  # take over legacy/local Claude runtime surfaces
--dry-run                  # preview mutating commands
--yes                      # non-interactive setup

MCP profiles

| Profile | Use when | |----|----| | minimal | You want only essential docs/filesystem tooling. | | web | You build web apps and want browser/docs helpers. | | backend | You focus on server-side projects. | | research | You need search and extraction tooling. | | full | You want every bundled MCP server enabled. | | custom | You want to choose exact MCP servers interactively; not available with --yes. |

When selected, Context7 and Tavily prompts include dashboard links for getting API keys.

What it creates

target-project/
├── CLAUDE.md                     # created empty if missing
├── .claude/
│   ├── CLAUDE.md
│   ├── settings.json             # copied from example, gitignored
│   └── settings.local.json       # when local settings are provided, gitignored
├── .mcp.json                     # generated, gitignored
├── .repo-pattern/
│   ├── .gitignore               # *
│   ├── .repo-pattern.json
│   └── .repo-pattern.lock.json

repo-pattern preserves an existing root CLAUDE.md and keeps machine-local values out of git.

Safety defaults

• .mcp.json is gitignored because it may contain local values.
• .repo-pattern/.repo-pattern.json is generated from .repo-pattern.example.json and kept inside .repo-pattern/.
• .claude/ is generated from .claude.example/ and gitignored.
• Basic OS/IDE noise (.DS_Store, Thumbs.db, .vscode/, .idea/) is gitignored during setup.
• .claude/settings.json keeps hooks: {} and disables commit attribution by default; interactive setup can turn it on or use a custom trailer.
• No vendored ECC skills, commands, hooks, or scripts are installed. ECC rules are auto-installed for ECC pipelines and opt-in for gstack/none.
• Karpathy-inspired Claude Code guidelines are included in .claude/CLAUDE.md from multica-ai/andrej-karpathy-skills (MIT).
• Optional external skills are user opt-in only: --with-skill taste, --with-skill document-specialist, --with-skill ui-ux-pro-max, --with-skill impeccable, --with-skill huashu-design, --with-skill nextjs-pattern, --with-skill fastapi-pattern, --with-skill herdr, or interactive setup.

External guidance and skills

| Name | Integrated as | Source | License | |----|----|----|----| | karpathy-guidelines | Built-in .claude/CLAUDE.md guidance | https://github.com/multica-ai/andrej-karpathy-skills | MIT | | gstack | Global setup pipeline via --setup-pipeline gstack | https://github.com/garrytan/gstack | MIT | | taste | Optional Claude Code plugin via --with-skill taste | https://github.com/Leonxlnx/taste-skill/ | MIT | | document-specialist | Optional .claude/skills/ install via --with-skill document-specialist | https://github.com/SpillwaveSolutions/document-specialist-skill/ | NOASSERTION — no upstream license declared during review on 2026-07-06 | | ui-ux-pro-max | Optional Claude Code plugin via --with-skill ui-ux-pro-max | https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/ | MIT | | impeccable | Optional Claude Code plugin via --with-skill impeccable | https://github.com/pbakaus/impeccable/ | Apache-2.0 | | huashu-design | Optional .claude/skills/ install via --with-skill huashu-design (multimedia scripts may need Playwright/Python/ffmpeg; install can take ~10 minutes, so opt in deliberately) | https://github.com/alchaincyf/huashu-design/ | MIT | | nextjs-pattern | Optional .claude/skills/ install via --with-skill nextjs-pattern | https://github.com/NegiKirin/nextjs-pattern/ | MIT | | fastapi-pattern | Optional .claude/skills/ install via --with-skill fastapi-pattern | https://github.com/NegiKirin/fastapi-pattern/ | MIT | | herdr | Optional .claude/skills/ install via --with-skill herdr; control commands require HERDR_ENV=1 inside Herdr | https://github.com/ogulcancelik/herdr/ | AGPL-3.0-or-later or commercial |

Learn more

Full setup details live in docs/repo-pattern/setup-guide.md. Third-party license notices are listed in THIRD_PARTY_NOTICES.md.

From a source checkout, replace repo-pattern with:

node scripts/repo-pattern.mjs