claude-leverage

Not every task in a coding session needs the most capable model. This repo orchestrates Claude Code subagents so that research, code review, test runs, and trivial commits are handled by cost-efficient models — while implementation and architecture stay on the latest Opus. The result: 30–70% token savings on typical development work, with no compromise on code quality.

Quick install:

/plugin marketplace add Filip-Podstavec/claude-leverage
/plugin install claude-leverage@filip-podstavec

Why

Claude Code is an orchestration layer, not a single model call. The most capable model does not need to handle every task - a code review can run on Sonnet while Opus plans architecture, a trivial commit can use Haiku while Sonnet handles complex changes. This repo provides building blocks for routing work across model tiers to reduce token costs and preserve output quality at the same time.

Security guardrails belong in hooks (deterministic, always-on), not in subagent prompts (active only when that prompt runs). Workflow guidance belongs in slash commands and subagent prompts. This separation is intentional.

Architecture

graph TB
    subgraph Main["Opus Main Session"]
        USER["User prompt"]
    end

    subgraph Commands["Slash Commands - workflow routing"]
        CS["/commit-smart"]
        CR["/code-review"]
        TT["/test"]
        GCT["/gather-context"]
        DS["/docs-sync"]
    end

    subgraph Agents["Subagents - model-specific execution"]
        GC["git-committer<br/><small>Sonnet</small>"]
        GCQ["git-committer-quick<br/><small>Haiku</small>"]
        CRA["code-reviewer<br/><small>Sonnet</small>"]
        TR["test-runner<br/><small>Sonnet</small>"]
        RX["repo-explorer<br/><small>Haiku</small>"]
        RA["research-agent<br/><small>Sonnet</small>"]
        CG["context-gatherer<br/><small>Sonnet</small>"]
        DU["docs-updater<br/><small>Sonnet</small>"]
    end

    subgraph Hooks["Hooks - deterministic security layer"]
        BS["block-secrets-precommit"]
        BD["block-dangerous-git"]
    end

    subgraph Snippets["CLAUDE.md Snippets"]
        CRR["code-review-routing"]
        TRR["test-routing"]
    end

    USER --> CS & CR & TT & GCT & DS
    USER -.->|"explore"| RX
    CS -->|"non-trivial"| GC
    CS -->|"trivial < 20 lines"| GCQ
    CR --> CRA
    TT --> TR
    GCT --> CG
    DS --> DU

    Hooks -.->|"intercepts every Bash call"| Main
    Hooks -.->|"intercepts every Bash call"| Agents
    Snippets -.->|"configures routing in"| Main

What's inside

Components

Agents

Commands

Hooks

CLAUDE.md Snippets

Workflow example

A typical development cycle using claude-leverage:

1. /gather-context                     → Sonnet pre-fetches implementation context
2. Explore codebase if needed          → Haiku repo-explorer (Opus saves context)
3. Write code                          → Opus main session (guided by context package)
4. /code-review                        → Sonnet reviews (Opus saves context)
5. Apply fixes from review             → Opus applies, guided by Sonnet's report
6. /test                               → Sonnet runs tests, reports failures
7. Fix failing tests                   → Opus fixes, guided by Sonnet's report
8. /commit-smart                       → Routes automatically:
   ├─ trivial (1-2 files, <50 lines)   → commits directly in session
   ├─ trivial + single file <20 lines  → optionally Haiku subagent
   └─ non-trivial                      → Sonnet git-committer subagent
9. /docs-sync                         → Sonnet flags stale README/CHANGELOG, Opus applies
10. Hooks run silently on every step   → block secrets, prevent force push

Result: Opus handles only architecture and code changes. Reviews, tests, and commits run on cheaper models. Hooks enforce security without relying on any prompt.

Quick install (recommended)

The fastest way to get the full claude-leverage stack is to install it as a Claude Code plugin. This installs all agents, commands, and hooks at user scope by default - they work across every project on your machine.

In a running Claude Code session:

/plugin marketplace add Filip-Podstavec/claude-leverage
/plugin install claude-leverage@filip-podstavec

That's it. All eight agents, five commands, and two hooks are now available globally. Verify with /agents and /commands.

Update and uninstall:

/plugin marketplace update          # refresh catalog
/plugin update claude-leverage      # update to latest version
/plugin uninstall claude-leverage@filip-podstavec

Upgrading from 0.1.x: If you see a hooks loading error after updating (Failed to load hooks from .../0.1.0/hooks/hooks.json), the old cached version has a known issue. The platform does not clean old cache on update or reinstall — you must delete it manually:

# Linux/macOS
rm -rf ~/.claude/plugins/cache/filip-podstavec/claude-leverage/0.1.0

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\plugins\cache\filip-podstavec\claude-leverage\0.1.0"

Then run /reload-plugins in your Claude Code session. This is a Claude Code platform issue — old plugin cache versions are not cleaned up automatically.

Scope notes: By default, plugins install to user scope (~/.claude/plugins/) and apply across all your projects. If you install with project scope (via the interactive /plugin UI), be aware of a known limitation: project-scoped plugins cannot be promoted to user scope through the UI - you would need to uninstall and reinstall. For most users, the default user scope is the right choice.

CLAUDE.md snippets and workflow guides are documentation, not Claude Code primitives - the plugin does not install them. Copy what you need from claude-md-snippets/ into your project's CLAUDE.md file.

Manual install (advanced)

Prefer to cherry-pick individual components or modify them before installing? You can copy files directly into ~/.claude/ or your project's .claude/ directory. This bypasses the plugin system - useful when you want to fork specific agents, run a custom version, or install only a subset.

git clone https://github.com/Filip-Podstavec/claude-leverage.git
cd claude-leverage

Open the repo in Claude Code and tell it to set you up. The agent will walk you through three groups of components, explain what each does, and let you pick what to install and where.

1. Security hooks (recommended for everyone)

Impact: Zero change to your workflow. Hooks run silently in the background on every tool call and block dangerous operations before they happen.

Scope: User-level only (~/.claude/hooks/) - hooks protect all your projects, not just one.

mkdir -p ~/.claude/hooks
cp hooks/*.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

Then register in ~/.claude/settings.json - see hooks/README.md for the JSON config.

2. Cost optimization (no quality impact)

Impact: Commits that don't require deep reasoning get routed to cheaper models (Sonnet/Haiku) instead of consuming Opus context. Your code quality stays the same - only the commit workflow gets delegated.

Scope: Choose one:

• User-level (~/.claude/agents/, ~/.claude/commands/) - available in all your projects
• Project-level (.claude/agents/, .claude/commands/) - committed to your repo, shared with the team

# User scope
mkdir -p ~/.claude/agents ~/.claude/commands
cp agents/git-committer.md agents/git-committer-quick.md ~/.claude/agents/
cp commands/commit-smart.md ~/.claude/commands/

# - OR - Project scope
mkdir -p .claude/agents .claude/commands
cp agents/git-committer.md agents/git-committer-quick.md .claude/agents/
cp commands/commit-smart.md .claude/commands/

3. Quality workflows (adds new capabilities)

Impact: Adds code review and test delegation workflows. Sonnet handles the review/test execution, Opus only sees the structured report and applies fixes. Saves Opus context while adding structured quality gates.

Scope: Same choice as above - user-level or project-level. Snippets go into your CLAUDE.md.

# User scope
cp agents/code-reviewer.md agents/test-runner.md agents/repo-explorer.md agents/research-agent.md agents/context-gatherer.md agents/docs-updater.md ~/.claude/agents/
cp commands/code-review.md commands/test.md commands/gather-context.md commands/docs-sync.md ~/.claude/commands/

# - OR - Project scope
cp agents/code-reviewer.md agents/test-runner.md agents/repo-explorer.md agents/research-agent.md agents/context-gatherer.md agents/docs-updater.md .claude/agents/
cp commands/code-review.md commands/test.md commands/gather-context.md commands/docs-sync.md .claude/commands/

Then copy the snippets you want from claude-md-snippets/ into your CLAUDE.md.

After install

Run /agents or /commands in a running Claude Code session to pick up changes without restarting.

Philosophy

Three layers of defense

Hooks are the primary safety layer because they cannot be bypassed by prompt injection or model hallucination. Commands encode workflow logic. Subagent prompts are the last resort.

Model tiering

Each subagent declares its model explicitly in frontmatter. No implicit inheritance.

License

MIT

Contributing

See CONTRIBUTING.md.