Structured guardrails for Claude Code. Every rule tuned to how the model actually thinks — minimal touch, maximum impact.
CCO adds just enough structure to prevent over-engineering, scope creep, and silent assumptions — without slowing Claude down.
| Without CCO | With CCO |
|---|---|
| Adds AbstractValidatorFactory for simple validation | Only requested changes |
| Edits 5 files when asked for 1 fix | Scoped to the task |
| Guesses requirements silently | Stops and asks |
| Method grows to 200 lines | ≤50 lines, ≤3 nesting |
| Hallucinates imports that don't exist | Verifies before writing |
| Reports false positives | Reads context, discards FPs |
macOS / Linux:
mkdir -p ~/.local/bin && curl -fsSL https://github.com/sungurerdim/ClaudeCodeOptimizer/releases/latest/download/cco-$(uname -s | tr A-Z a-z)-$(uname -m) -o ~/.local/bin/cco && chmod +x ~/.local/bin/cco && ~/.local/bin/cco installWindows (PowerShell):
$b="$HOME\.local\bin"; New-Item $b -ItemType Directory -Force >$null; irm https://github.com/sungurerdim/ClaudeCodeOptimizer/releases/latest/download/cco-windows-amd64.exe -OutFile "$b\cco.exe"; & "$b\cco.exe" installRestart Claude Code. Done.
/cco-blueprint— Create a project profile in CLAUDE.md (priorities, constraints, targets)/cco-align— Architecture gap analysis/cco-optimize— Scan and fix security, quality, and hygiene issues
~/.claude/
├── rules/cco-rules.md # Auto-loaded every session (passive)
├── skills/cco-*/SKILL.md # Slash commands (active)
└── agents/cco-agent-*.md # Specialized subagents
Passive — Rules load automatically at session start. Scope control, complexity limits, verification, and security patterns are always active. No commands needed.
Active — Skills are invoked via /cco-* slash commands. Each skill orchestrates a specific workflow (optimize, commit, PR, etc.).
Feature branch workflow:
main → /cco-commit → feature branch → work → /cco-pr → main
/cco-commit detects when you're on main and creates a feature branch automatically. /cco-pr creates a conventional-commit PR for clean changelogs.
| Skill | What it does | Key Flags |
|---|---|---|
/cco-optimize |
Scan and fix security, types, performance, hygiene issues | --auto, --preview, --scope=X, --loop |
/cco-align |
Analyze architecture gaps and fix structural issues | --auto, --preview |
/cco-commit |
Quality-gated atomic commits with branch management | --preview, --single, --staged-only |
/cco-pr |
Create release-please compatible PRs with auto-merge | --auto, --preview, --no-auto-merge, --draft |
/cco-blueprint |
Profile project health, set targets, track progress | --auto, --init, --refresh, --scope=X |
/cco-docs |
Find documentation gaps and generate missing content | --auto, --preview, --scope=X, --update |
/cco-research |
Multi-source research with CRAAP+ reliability scoring | --quick, --deep |
/cco-update |
Check for updates and install latest version | --auto, --check |
8 skills · 3 specialized agents · Core rules via auto-loaded rules file
Rules are active in every session — no commands needed.
| Category | What it does |
|---|---|
| Scope Control | Every changed line traces to the request; unrelated issues mentioned, not fixed |
| Complexity Limits | CC≤15, Method≤50 lines, File≤500 lines, Nesting≤3, Params≤4 |
| Anti-Overengineering | No abstraction unless it solves a current problem in multiple places |
| Production Standards | Security, privacy, performance, error handling applied by default |
| Output Brevity | Concise responses; no unnecessary praise, filler, or emojis |
| Verification | Read before write; verify imports and APIs exist before using |
| Uncertainty Protocol | State confidence levels; ask before proceeding on ambiguous tasks |
| Security Baseline | Flag secrets in source, bare catches, unsanitized data, eval/pickle |
Full reference: docs/rules.md
- Getting Started — First 10 minutes
- Skills — Flags, scopes, and examples
- Agents — Specialized agents
- Rules — Full rules reference
- Architecture — System design and structure
Optional add-ons that complement CCO.
| Extra | Description |
|---|---|
| Statusline | Git, model, and context info in your Claude Code status bar |
/cco-update
Or re-run the installer:
cco install # macOS/Linux
cco.exe install # Windowscco uninstallManual removal
rm -f ~/.claude/rules/cco-rules.md
rm -rf ~/.claude/skills/cco-*/
rm -f ~/.claude/agents/cco-agent-*.mdMigration from previous versions
| Version | Distribution | Mechanism |
|---|---|---|
| v1.x | pip package | Python dependency |
| v2.x | Claude Code plugin | Marketplace + hooks |
| v3.x | Install script | curl/irm + rules/commands/agents |
| v4.x | Go binary | Single cross-platform binary + rules/skills/agents |
From v3: Run the v4 installer — it automatically migrates commands/ to skills/ and cleans up legacy files. Or use /cco-update.
From v2: Uninstall plugin (/plugin uninstall cco@ClaudeCodeOptimizer + /plugin marketplace remove ClaudeCodeOptimizer), then run the v4 installer.
From v1: Uninstall pip package (pip uninstall claudecodeoptimizer), then run the v4 installer.
MIT License