cc-rig

Set up Claude Code the right way, in under a minute.

Getting Started · How It Works · What Gets Generated · Going Deeper · FAQ

Most Claude Code projects run on a CLAUDE.md and not much else. The rest of the configuration surface (agents, hooks, skills, plugins, memory, permissions) goes unused because the knowledge to set it up is scattered across docs, blog posts and community repos. The community has built ways to discover what's available. The gap is resolution: figuring out which options matter for your stack and how they should work together.

cc-rig resolves it. Tell it what you're building and how you like to work. It writes 30-65 native Claude Code files tuned to your framework. No lock-in. Just files that Claude Code reads on startup.

Before and after

A typical Claude Code project:

CLAUDE.md

After cc-rig init (one command, two questions, ~30 seconds):

CLAUDE.md                    # Cache-aware, framework-tuned, under 100 lines
CLAUDE.local.md              # Personal preferences (gitignored)
.claude/settings.json        # Permissions, hooks, 47 curated plugins
.claude/agents/              # 3-19 specialized agents with YAML frontmatter
.claude/commands/            # 6-19 slash commands matched to your workflow
.claude/hooks/               # Auto-format, lint gates, safety blocks
.claude/skills/              # Community skills from 17 repos
agent_docs/                  # Framework-specific guides (auto-loaded via @import)
memory/                      # Git-tracked team knowledge across sessions

Nothing proprietary. Delete cc-rig tomorrow and everything keeps working.

Install

python3 -m venv ~/.cc-rig
source ~/.cc-rig/bin/activate
pip install cc-rig

Python 3.9+. Includes the full-screen TUI wizard with arrow keys, radio buttons, checkboxes, colors, tables and progress bars.

Already have a venv? Just pip install cc-rig inside it. The venv step above is for first-time setup. Without it, macOS and Linux block global pip installs.

Prefer pipx? pipx install cc-rig works too. No venv needed.

Next session? Remember to source ~/.cc-rig/bin/activate before running cc-rig.

• Works best with Claude Code v2.1.50+. Older versions or missing installs get a warning, but cc-rig generates everything anyway.

Getting Started

Start a new project

The interactive wizard walks you through it. You get a full-screen TUI with arrow-key navigation, radio buttons and checkboxes.

cc-rig init

Or skip the wizard and specify everything directly:

cc-rig init --workflow gstack --template fastapi --name my-api

Set up an existing project

Already have a codebase? cc-rig detects your stack from package.json, go.mod, Cargo.toml, pyproject.toml and more. It proposes what to add and won't touch existing files.

cd my-existing-project
cc-rig init --migrate

Use a team config

A teammate already set up cc-rig? Load their config and get the same setup:

cc-rig init --config .cc-rig.json

Quick picker

Don't want the full wizard? Pick from numbered lists:

cc-rig init --quick

How It Works

cc-rig is workflow-first. You pick how you like to work, then optionally pick your stack. The two axes compose independently: any workflow works with any template.

How you like to work: Workflows

Workflow is the primary axis. It determines your agents, commands, hooks, process skills, and features.

Community workflows install their original process skills with full attribution. For example, gstack installs /plan-ceo-review, /plan-eng-review, /gstack-review, /ship, /document-release directly from garrytan/gstack.

Backward-compatible aliases: verify-heavy resolves to superpowers, gtd-lite resolves to gtd.

What you're building: Stack (optional)

Stack is secondary enrichment. It adds framework-specific tool commands, agent docs, rules, and language-specific reviewer agents. The default is Generic (no stack-specific content).

Add-ons

Some workflows include compound features that span multiple Claude Code primitives:

Spec Workflow (spec-driven, aihero, superpowers). Plan-first development: /spec-create and /spec-execute commands, pm-spec and implementer agents, specs/TEMPLATE.md starter file. Based on Pimzino's spec workflow.

GTD System (gtd). Getting Things Done for Claude Code: /gtd-capture, /gtd-process, /daily-plan commands, pre-created tasks/inbox.md, tasks/todo.md and tasks/someday.md. Based on adagradschool's cc-gtd.

Worktrees (gstack, aihero, spec-driven, superpowers, gtd). Parallel development using Claude Code's native git worktree support: parallel-worker agent and /worktree command. For batch orchestration, cc-rig worktree spawn launches multiple Claude sessions in isolated worktrees simultaneously. Each gets its own branch, runs independently, and can be merged via PR when done.

Mix and match

# Just the gstack workflow, no specific stack
cc-rig init --workflow gstack

# FastAPI with superpowers - maximum rigor
cc-rig init --template fastapi --workflow superpowers

# Go microservice with GTD task tracking
cc-rig init --template gin --workflow gtd

What Gets Generated

cc-rig generates native Claude Code files, the same formats from the official docs. Everything is editable, nothing is proprietary. For the complete reference with all tables, see docs/generated-output.md.

CLAUDE.md

Targets under 100 lines. Static content first, dynamic content last. Claude Code's prompt cache is prefix-matched, so every wasted token costs money on every API call. Includes project identity, stack, tool commands, guardrails (including 4 cache-specific rules), compaction survival instructions, framework-specific rules and @import references to deeper docs. A companion CLAUDE.local.md is generated for personal preferences (not git-tracked).

Agents

Your workflow and stack together determine which agents ship. Speedrun gets 3. Superpowers gets the full set, including an architect and security auditor on Opus with effort: high, and a parallel worker that runs in isolated worktrees. Each agent gets its own system prompt, model assignment, and tool restrictions in YAML frontmatter (up to 12 of 14 supported fields).

Plus pr-reviewer, pm-spec, test-writer, refactorer, implementer, doc-writer, techdebt-hunter, db-reader, build-fixer, e2e-runner and language-specific reviewers for Go, Rust, and Java. See all 19 agents.

Slash Commands

Workflows you trigger with / in Claude Code. Your workflow preset determines the set.

Plus /test, /research, /assumptions, /learn, /refactor, /optimize, /techdebt, /spec-execute, /daily-plan, /gtd-capture, /gtd-process, /security, /document. See all 19 commands.

Hooks

Shell scripts on Claude Code lifecycle events, configured in settings.json.

Up to 14 hooks from your workflow preset, plus up to 5 more from the harness level. See all hooks.

Skills

cc-rig downloads skills from the original community repos at init time and does not bundle or redistribute them. Your workflow determines the process skills: gstack installs Garry Tan's 6 skills from garrytan/gstack, superpowers installs obra's 11 from obra/superpowers. Your stack adds framework-matched content: Django projects get Django ORM and testing patterns from everything-claude-code, Go projects get static analysis, Rust projects get ownership and lifetime patterns.

Starter set (auto-installed at init):

• Framework-matched: Python projects get modern-python and property-based-testing, Next.js gets vercel-react-best-practices and next-best-practices, Go/Rust get static-analysis
• Cross-cutting: code review, security basics, TDD, debugging. Scaled by workflow (0 for speedrun, up to 14 for superpowers)
• project-patterns stub for your team's custom conventions

Optional skill packs (select during wizard or add later):

Browse the full ecosystem: skills.sh · awesome-claude-skills · skillsmp.com. Skill CLI commands.

Plugins

cc-rig curates 47 official Anthropic marketplace plugins and writes them into settings.json as enabledPlugins. Your language gets its LSP plugin, your template gets relevant integrations (Next.js gets Playwright, Laravel gets Laravel Boost), your workflow gets workflow plugins. Plugins are self-contained: no manual MCP setup or binary downloads.

Memory, permissions, MCP, agent docs

cc-rig generates a team memory layer (memory/): 5 git-tracked files for decisions, patterns, gotchas, people and session logs. A Stop hook saves learnings before sessions end, a PreCompact hook does the same before context compaction. Memory loads on demand via Read tool, not baked into CLAUDE.md, keeping the cached prefix stable.

Context intelligence (v2.2): Every generated CLAUDE.md includes compaction survival instructions and cache guardrails. The B1+ harness adds a PreCompact hook that outputs project essentials before context compaction and documents 14 cache-break vectors. The B2+ harness adds session telemetry (token usage, cost tracking, cache hit stats) written to .claude/telemetry.jsonl on every session end. cc-rig doctor checks your CLAUDE.md for cache anti-patterns and parses session JSONL to warn when cache hit ratios drop below 40%.

Permissions are configured in settings.json with sensible allow/deny defaults. Safety hooks block .env edits, pushes to main and destructive rm commands.

MCP servers are configured in .mcp.json per template (PostgreSQL, Playwright). GitHub is now an official plugin, no MCP setup needed.

Agent docs in agent_docs/ provide framework-specific reference (architecture, conventions, testing, deployment, cache-friendly workflow) loaded via @import syntax.

Full details for all of the above.

Going Deeper

Expert mode

Full control over agents, commands, hooks, skills, MCP servers, permissions, features and custom CLAUDE.md rules. Starts from your workflow's defaults:

cc-rig init --expert

Autonomous mode

Claude works through a task list while you're away.

cc-rig harness init --lite        # Task tracking + budget + context survival hook
cc-rig harness init               # + enforcement gates + session telemetry + init-sh.sh
cc-rig harness init --autonomy    # + loop script, 5-step PROMPT.md, progress ledger

Each level builds on the previous. The wizard's "Custom" option lets you enable any combination of task tracking, budget awareness, verification gates, context awareness, session telemetry and autonomy loop independently. A 6th option enables the ralph-loop plugin, Anthropic's official autonomous iteration loop.

The autonomy level generates loop.sh and PROMPT.md, a bash loop that feeds tasks to Claude one at a time with fresh context. Based on the Ralph Wiggum technique by Geoffrey Huntley. Safety rails included: iteration limits, budget enforcement, checkpoint auto-commits, stuck detection and a cost summary on exit.

Warning: loop.sh uses --dangerously-skip-permissions. Run inside a Docker container or sandboxed environment. Full autonomous mode details.

For teams

Every cc-rig init saves a config file. Commit it and teammates get the same setup:

cc-rig init --config .cc-rig.json    # Same agents, hooks, permissions

Export portable configs, lock configs to prevent modification, compare configs across projects. Team config commands.

Health check and cleanup

cc-rig doctor                 # Check project health (files, hooks, permissions, cache, manifest)
cc-rig doctor --fix           # Auto-fix safe issues
cc-rig clean                  # Remove generated files using the manifest

Run cc-rig --help or see the full CLI reference.

FAQ

You could write CLAUDE.md yourself. But a fully configured project also needs settings.json with hooks and permissions, agent markdown files with YAML frontmatter and tool restrictions, slash command files, skills, MCP config, memory files and agent docs, all with correct cross-references. cc-rig generates everything in seconds with content specific to your framework.

Yes. cc-rig init --migrate scans your repo, detects your stack and proposes what to add. It only writes new files and won't touch anything that already exists.

Yes. Everything is plain text. Edit whatever you want. cc-rig won't overwrite your changes. Generate once, own forever. To re-run the wizard with your existing choices pre-filled, use cc-rig config update. It shows what changed and regenerates on confirmation. For personal preferences, use CLAUDE.local.md (not git-tracked) to avoid conflicts with team config.

cc-rig handles both community skills and official Anthropic plugins. For skills, cc-rig downloads from 17 community repos at init time, with 6 optional packs for deeper coverage. For plugins, cc-rig curates 47 official marketplace plugins across 6 categories (LSP, integration, workflow, style, autonomy, utility) and writes enabledPlugins into settings.json with defaults resolved by language, template and workflow. You can install any additional skill from skills.sh, awesome-claude-skills or any GitHub repo.

A harness that lets Claude work through a task list unattended. It uses structural enforcement: hooks that block commits when lint fails, a utility script (init-sh.sh) wrapping your test/lint/format commands, iteration limits, budget enforcement with cost tracking, checkpoint auto-commits, stuck detection and an emergency stop. On exit you get a cost summary showing total tokens and estimated spend. Set it up, walk away, review the results.

cc-rig is free and open source. Claude Code itself requires an Anthropic plan. cc-rig keeps CLAUDE.md lean, generates cache guardrails, and tracks cache hit rates via session telemetry to minimize your token costs. Cached prompt tokens cost 10% of uncached tokens.

cc-rig requires Python 3.9+. Some Linux distros (e.g. Ubuntu 20.04) ship Python 3.8. Check with python3 --version. If you're on 3.8, install a newer Python:

sudo apt install python3.9 python3.9-venv python3.9-distutils
python3.9 -m venv .venv && source .venv/bin/activate
pip install cc-rig

Community & Ecosystem

cc-rig's skills are downloaded at init time from the original repos. cc-rig does not bundle or redistribute them. Key sources:

• affaan-m/everything-claude-code - Framework-specific skills: Python, Django, Spring Boot, Laravel, Go, Rust + SDLC (MIT)
• obra/superpowers - 14 SDLC workflow skills (MIT)
• garrytan/gstack - 6 cognitive gear skills: plan, review, ship, document (MIT)
• mattpocock/skills - 7 PRD-driven flow skills: grill-me, TDD, architecture (MIT)
• trailofbits/skills - 30+ security + modern dev skills (CC-BY-SA-4.0)
• anthropics/skills - 16 official Anthropic skills (Apache 2.0)

Plus 11 more repos from HashiCorp, Vercel, Supabase, PlanetScale, Addy Osmani and others. See all 17 source repos. The broader ecosystem: skills.sh · awesome-claude-skills · skillsmp.com.

cc-rig's design is informed by Boris Cherny's workflow principles, Thariq's prompt caching insights, and the Ralph Wiggum technique by Geoffrey Huntley. Full research & inspiration list.

Contributing

PRs welcome, especially new templates, new workflow presets, community skill integrations and bug fixes. Please open an issue first for large changes.

git clone https://github.com/runtimenoteslabs/cc-rig.git
cd cc-rig
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/
ruff check cc_rig/

pytest and ruff are dev-only.

Ready to try it?
pip install cc-rig && cc-rig init

If cc-rig saves you setup time, star the repo.

License

MIT