cc-rig 4.0.0

Set up Claude Code right, then keep it right.

Two Commands · Why Cache · Install · Tune · What Gets Generated · FAQ

cc-rig started with one mission: make setting up Claude Code painless, back when the config surface was a scattered mess of docs and community repos. That part is mostly solved now. Native tooling scaffolds a CLAUDE.md and the marketplace has the plugins, so getting a config is easy. Getting it right is still the hard part: most configs are generic, bloat the context window, skip the guards that stop a destructive command and quietly break the prompt cache.

cc-rig gets your config right, then keeps it right. cc-rig init generates a lean, stack-tailored setup in one command: a tight CLAUDE.md, hooks that gate on your framework's real test and lint commands, plus agents, skills, memory and curated plugins. cc-rig tune then scores that config on six published dimensions, ranks what to fix and applies the safe fixes, so it stays correct as your project and Claude Code both move.

cc-rig init     # generate a lean, stack-tailored config
cc-rig tune     # score it, rank what to fix, apply the safe fixes

Native Claude Code files, nothing proprietary. Delete cc-rig tomorrow and your project keeps working.

The two commands

cc-rig init writes the config

Tell it what you're building and how you like to work. It writes 30-65 native Claude Code files tuned to your framework: a cache-aware CLAUDE.md, settings with hooks and permissions, specialized agents, slash commands, skills, memory and curated plugins.

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, 87 curated plugins
.claude/agents/              # 3-19 specialized agents with YAML frontmatter
.claude/commands/            # 6-19 slash commands matched to your tier
.claude/hooks/               # Auto-format, lint gates, safety blocks
.claude/skills/              # Community skills from 14 repos
.github/workflows/claude.yml # Claude reviews your PRs (opt-out for quick tier)
agent_docs/                  # Framework-specific guides (auto-loaded via @import)
memory/                      # Git-tracked team knowledge across sessions

cc-rig tune keeps it correct

Run it any time. It reads your config, plus your session history when there is one, scores six weighted dimensions and ranks the fixes by severity. Where your own logs can measure what a cache problem costs, the finding carries that figure.

Real output on a hand-grown CLAUDE.md with a month of session logs (44 synthetic Opus 5.5 sessions, the same scenario as the tune demo):

$ cc-rig tune
╭──────── cc-rig tune · acme-api ────────╮
│ 66 / 100   Getting There               │
│ cache reads 95%   ·   44 sessions seen │
╰────────────────────────────────────────╯
Dimension           Weight              Score
Cache hygiene          30%  ████████··     75
Safety guards          20%  ██········     20
Context discipline     15%  ██████████    100
Workflow fit           15%  ███████···     70
Verification           10%  █████·····     50
Currency               10%  ████████··     85

Top opportunities (ranked by impact)
  1. Add a verification gate   [high]  [safe fix]
     Require tests/lint to pass before committing (guardrail or commit hook).
  2. Add destructive-command protection   [high]  [safe fix]
     Block rm -rf, DROP TABLE, etc. via a PreToolUse hook or a guardrail.
  3. Remove the date/timestamp from CLAUDE.md's static section   ~$0.02/mo  [--fix-unsafe]
     Line 3 changes the cached prefix, re-creating it every session. Move it below '## Current Context' or into CLAUDE.local.md.
  4. Add a Commands section to CLAUDE.md   [med]
     List build/test/lint commands so Claude uses the right tooling.
  5. Add a block-push-to-main protection   [med]  [safe fix]
     Prevent accidental direct pushes to the default branch.
  6. Add a secrets guardrail   [med]  [safe fix]
     Tell Claude never to read, output, or log API keys, tokens, or secrets.
  7. Pin the Claude Code version in CLAUDE.md   [low]  [safe fix]
     A pinned version line makes drift visible after a CC upgrade.

Run `cc-rig tune --fix` to apply 5 safe fix(es).

The cache finding is real but small here: this CLAUDE.md is only 251 bytes, so re-writing it 44 times a month costs about two cents. The same date in a 2,000-token CLAUDE.md across 100 sessions a month would cost roughly $1.60. Either way, the missing safety guard and verification gate are what actually put this project at risk, so they rank first.

cc-rig tune --fix applies the safe fixes (backed up via FileTracker), shows a diff and re-scores. --ci gates a pipeline on a threshold. --badge emits a Shields.io endpoint. Full detail in the tune section.

Why cache hygiene

Claude Code assembles every request as a prefix (tools, system prompt, your CLAUDE.md, then the conversation) and caches it. If the prefix is byte-for-byte identical to a previous request, the cached tokens cost 10% of the uncached price ($0.20/M vs $2.00/M on Sonnet 5.5). A single changed byte invalidates everything after it, and that part is written to the cache again at the cache-write rate (1.25x to 2x the uncached price).

Claude Code does the caching on its own, so cc-rig doesn't claim the savings. What a config can do is break it: a date in the static zone, a hook toggled mid-session, an inlined memory file that changes every session, a model switch. What that costs depends on your CLAUDE.md size, model and session count, and cc-rig tune reports it from your own logs. cc-rig treats it as a correctness bug, not a cost line: the config is doing something it shouldn't, whatever the bill says. Inside a session, Claude Code's own /cost names the likely cause of each cache miss. cc-rig tune works one step earlier, on the repo itself: it traces the break to a specific config line and patches it before the next session starts.

Install

Try it without installing anything:

uvx cc-rig init        # or: pipx run cc-rig init

uv fetches cc-rig and its dependencies into a throwaway environment and runs it. Nothing is added to your system, and you always get the latest release. Good for a one-off run or a first look.

Install it permanently:

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.

• Compatible with Claude Code v2.1.287 (pinned, verified live). Works on v2.1.83+. 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 rigorous --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

cc-rig tune

cc-rig tune scores your Claude Code config, ranks what to fix and applies the safe fixes in place. It reuses the same engine that generates configs, so a recommendation and an applied fix are the same code path.

The score model

A composite 0-100 score, decomposed into published, impact-weighted dimensions. The weights are public, so you can audit the number.

Findings rank by severity. Cache findings also carry a monthly dollar figure when your session logs (~/.claude/projects/) can ground one, computed with zero extra LLM calls from your CLAUDE.md size, your model's cache write and read rates, your cache TTL mix and your session count. A figure of $1/mo or more ranks ahead of the severity order. Anything smaller is shown but never outranks a structural finding of the same severity, so a missing destructive-command guard always sits above a few cents of cache churn. With no session history, the dollar figures are left out rather than guessed.

Three modes

cc-rig tune              # the human report (score + ranked opportunities)
cc-rig tune --fix        # apply safe fixes, show a diff, re-score
cc-rig tune --fix-unsafe # also apply fixes that relocate content (opt-in)
cc-rig tune --ci         # exit non-zero below --min-score (pipeline gate)
cc-rig tune --json       # machine-readable
cc-rig tune --badge      # Shields.io endpoint JSON

--fix applies additive, safe changes only by default (version pin, guardrail additions, verification gates): every change is backed up to .cc-rig-backup/ via FileTracker. The safety contract is the Ruff and Snyk model: never apply a fix that could introduce a worse problem than it removes. Anything that relocates user content is opt-in behind --fix-unsafe.

A freshly generated project scores 100/100 with zero opportunities on the quick and standard tiers, for all 16 stacks. On rigorous, 13 stacks score 100. Django, Go stdlib and Spring Boot score 98, because their framework guidance pushes CLAUDE.md past the size threshold. The tool grades its own output to the same bar it grades yours, and it says so when that output falls short.

How It Works

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

How you like to work: Tiers

Your tier is the primary axis. It determines agents, commands, hooks, plugins and features.

The three tiers are depth settings on one spine. They define how many agents ship, what hooks fire and which safety nets are active.

Legacy workflow names still work on the CLI for backward compatibility: --workflow speedrun resolves to quick, --workflow verify-heavy resolves to rigorous and so on. They map to a tier; there is no separate pack to choose.

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). This per-stack tailoring is what makes the tuner's gates correct: a FastAPI project gates on pytest and ruff, Next.js on vitest and tsc, Rust on cargo test and clippy.

Add-ons

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

Spec Workflow (rigorous tier). 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 (opt-in feature). Getting Things Done for Claude Code: /gtd-capture, /gtd-process, /daily-plan commands and pre-created task files. Based on adagradschool's cc-gtd.

Worktrees (standard + rigorous tiers). 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.

Mix and match

# Rigorous tier, no specific stack
cc-rig init --workflow rigorous

# FastAPI with the standard tier
cc-rig init --template fastapi --workflow standard

# Go microservice, rigorous tier
cc-rig init --template gin --workflow rigorous

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, see docs/generated-output.md.

CLAUDE.md

Targets under 100 lines, leaned to the evidence: essential tooling (build, test, lint commands) and critical patterns only, no README duplication. Static content first, dynamic content last, so only the tail breaks cache. Includes project identity, stack, tool commands, guardrails (including cache-specific rules), compaction survival instructions and @import references to deeper docs. A companion CLAUDE.local.md is generated for personal preferences (not git-tracked).

Agents

Your tier and stack together determine which agents ship. quick gets 3. rigorous 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.

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 agents.

Slash Commands

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

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

Hooks

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

See all hooks.

Skills

cc-rig downloads skills from the original community repos at init time and does not bundle or redistribute them. Your tier determines the base skills (0 for quick, up to 14 for rigorous). 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 tier
• project-patterns stub for your team's custom conventions

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

The 64-skill catalog spans 14 source repos. Browse the broader ecosystem: skills.sh · awesome-claude-skills · skillsmp.com.

Plugins

cc-rig curates 87 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 + Stripe, Django gets Redis, Spring gets AWS), your tier 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/): 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 the Read tool and stays out of CLAUDE.md, so the cached prefix stays stable across sessions.

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 an official plugin, so no MCP setup is needed.

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

GitHub Actions. The github_actions feature generates .github/workflows/claude.yml using anthropics/claude-code-action@v1. Claude reviews every PR and responds to @claude mentions. The rigorous tier adds a second security-review job. Enabled by default for standard and rigorous tiers.

Full details for all of the above.

Keep it aligned

cc-rig tune is the headline return surface. A few more subcommands keep a project aligned as you work and as Claude Code moves week to week.

cc-rig savings          # cache hit rate and spend over time (from your logs)
cc-rig audit            # discipline read of recent sessions vs your tier
cc-rig drift            # what diverged: edited files, config, CC version pin
cc-rig refresh <area>   # re-run one generator with a diff preview, write on confirm
cc-rig retro            # weekly view: savings + audit + drift, one suggestion

• savings reads your local Claude Code session logs and reports what the prompt cache saved versus uncached input, a 4-week trend and the top cache breakers. It is the longitudinal companion to tune's point-in-time score. Nothing leaves your machine; state lives at ~/.cc-rig/baseline.json.
• audit scores observable signals from your session logs (cache hygiene, model pinning, cache read ratio, session shape) and gives a tier-fit verdict.
• drift compares the project against a fresh generation and against the pinned Claude Code version. Read-only.
• refresh <area> regenerates one area (agents, commands, skills, rules, settings or all) and shows a unified diff before it writes. Overwritten files are backed up.
• retro rolls the week into one summary, with a footer in the generated CLAUDE.md and a session-start nudge pointing you back to it.

Project state for the loop lives at .claude/cc-rig-state.json (git-friendly, no raw paths or user content).

Going Deeper

Expert mode

Full control over agents, commands, hooks, skills, MCP servers, permissions, features and custom CLAUDE.md rules. Starts from your tier'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.

Saving tokens (the deep guide)

cc-rig tune flags what breaks your cache and cc-rig savings tracks your hit rate over time. Under the hood, the generated config is built to keep the prompt cache warm:

• CLAUDE.md is static-first. Project identity, commands and guardrails at the top (never change). Current context at the bottom (changes every session). Only the tail breaks cache.
• Cache guardrails tell Claude not to edit CLAUDE.md mid-session, not to toggle hooks/plugins, not to switch models (use subagents instead) and to load memory via the Read tool.
• Compaction survival. A dedicated CLAUDE.md section tells Claude what to preserve when the context window is compacted. The harness adds a PreCompact hook that outputs project essentials before the wipe.
• JSONL deduplication. Extended thinking can log duplicate PRELIM entries to your session JSONL. The telemetry hooks deduplicate before accounting, so cost estimates are accurate.

Full guide: saving tokens with cc-rig

FAQ

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 - SDLC workflow skills (MIT)
• trailofbits/skills - security + modern dev skills (CC-BY-SA-4.0)
• anthropics/skills - official Anthropic skills (Apache 2.0)

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

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

Contributing

PRs welcome, especially new templates, new tier 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?
uvx cc-rig init  then  cc-rig tune

If cc-rig helped, star the repo.

License

MIT