claude-leverage

Make any repo AI-first - write sustainable code from the start, or refactor a legacy codebase to prepare it for agent-driven development.

_{Convention layer (AGENTS.md) is also read by any AGENTS.md-aware tool - Cursor, Windsurf, Copilot…}

A small, opinionated AI-coding-agent suite for Claude Code and Codex CLI: deterministic security hooks, cross-tool skills, and self-maintaining conventions that keep a repo safe for the next agent to modify.

Complements skills-based plugins like the official superpowers plugin; it does not try to replace them.

Contents

• The problem it solves
• Who it's for
• Quick start
• Install
• What you get
• How it works
• Benchmarks
• How it compares
• What's inside
• Why one repo for two tools
• Honest history
• Verify, update, uninstall
• License

The problem it solves

Shipping at velocity with AI agents is easy. Shipping in a way that the next agent (human or AI) opening the repo in six months can still safely modify is the hard part. That second part is what the hooks, conventions, and skills here automate - not just at session start, but continuously as the repo grows.

Three properties guide every decision in this repo:

1. Security by default - deterministic hooks, no model needed.
2. Self-maintaining as the repo grows - non-blocking nudges surface maintenance debt early.
3. Cross-tool by design - same AGENTS.md, same SKILL.md, same hook scripts in Claude Code and Codex. Author once.

Who it's for

• Freelancer on client repos - you ship features across many client codebases through agents, and each one has to stay safe to hand back. The security hooks and AGENTS.md conventions travel with you.
• Team inheriting a legacy repo - you've opened a six-month-old codebase with no docs. /repo-doctor scores its AI-readiness and names the highest-leverage gaps; the bootstrap skills make it navigable fast.
• Solo builder shipping at velocity - you want speed without the repo rotting into unmaintainable AI-slop. Self-maintenance nudges plus ADR/session memory keep intent intact.

Quick start

Inheriting or already have a repo? Start here. Install the plugin:

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

Then make the repo AI-ready, top-down:

1. /repo-doctor - read-only AI-readiness audit. Scores ~20 dimensions (Foundation / Why / What / In-code / Hygiene / Sync) and names the gaps that matter most.
2. Fix the top gaps it reports - usually /init-repo (drop in a root AGENTS.md), then /arch-map and /glossary-init for machine-readable module metadata and domain terms.
3. /refresh-context-map - build the manifest that powers just-in-time context surfacing, so the right anchors appear at edit time.

Starting a fresh repo? Install, then run /init-repo to drop in AGENTS.md, .gitignore patterns, and an optional structured-logging starter.

Full install (including Codex CLI) is below.

Install

Claude Code

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

That's it. Restart Claude Code (or run /skill list and /agents in a current session) to pick up all 15 skills and 2 subagents.

Codex CLI

Two ways to use the stack with Codex — they're complementary, not either/or.

A. Plugin marketplace (skills + hooks). Codex now has a plugin marketplace; add this repo as a marketplace source and install it from /plugins:

npm i -g @openai/codex        # one time

Then in a Codex session, open /plugins, add the marketplace from GitHub shorthand Filip-Podstavec/claude-leverage, open the claude-leverage plugin, and select Install plugin.

This delivers the skills and the security/nudge hooks (Codex sets CLAUDE_PLUGIN_ROOT for compatibility, so the same hooks/hooks.json works). It does not deliver the subagents or the /flaky-test command — Codex plugins don't load those — nor the global @AGENTS.md import. For the full stack, use option B.

B. Install script (full stack: + subagents + global AGENTS.md import).

# 1. Install Codex CLI itself (one time)
npm i -g @openai/codex

# 2. Clone this repo to a stable location
git clone https://github.com/Filip-Podstavec/claude-leverage.git ~/.local/share/claude-leverage
cd ~/.local/share/claude-leverage

# 3. Run the installer
bash scripts/install-codex.sh         # macOS / Linux / WSL2
# OR
pwsh scripts/install-codex.ps1        # Windows PowerShell

Optional: portable statusline

Five segments shown left-to-right: 5-hour rate limit, 7-day rate limit, current context window %, model name, git branch.

Claude-Code-only (Codex has no statusline). Single Python file, no jq dependency, works on Windows under Git Bash. Color thresholds: green <60 %, yellow 60-84 %, red ≥85 %.

# Copy into ~/.claude/ (overwrites only if you have no statusline configured)
cp statusline/statusline-command.sh ~/.claude/statusline-command.sh
chmod +x ~/.claude/statusline-command.sh

Then add to ~/.claude/settings.json:

"statusLine": {
  "type": "command",
  "command": "bash ~/.claude/statusline-command.sh"
}

Restart Claude Code. To opt out later: delete the statusLine block from settings.json.

What you get

How it works

Typical session for a security-sensitive feature, end-to-end:

sequenceDiagram
    autonumber
    actor User
    participant CC as Claude Code (Opus)
    participant Hook as scripts/hooks/*.sh
    participant SR as security-reviewer<br/>(Sonnet, read-only)
    participant Git

    User->>CC: edit src/auth/handler.py
    CC->>Hook: PostToolUse (Write/Edit)
    Hook-->>User: ai-first-nudge: "73 LOC no AIDEV-NOTE anchor"

    User->>CC: /security-review
    CC->>SR: Task (delegate)
    SR->>Git: git diff --cached
    Git-->>SR: staged diff
    SR-->>CC: Critical / Important / Nice<br/>(file:line citations)
    CC-->>User: relay report verbatim

    User->>CC: /adr-new "use HS256 not RS256 here"
    CC->>CC: write docs/adr/0007-...md (immutable)

    User->>CC: commit this
    CC->>Hook: PreToolUse (Bash: git commit)
    Note right of Hook: block-secrets-precommit<br/>scans staged diff
    Hook-->>CC: allow (no secrets)
    CC->>Git: commit (Conventional Commits)
    Note right of CC: push only when user asks<br/>(no auto-push in v1.4.4+)

    User->>CC: /session-log "wire HS256 auth + middleware"
    CC->>CC: write docs/sessions/YYYY-MM-DD-...md (distillate)

    Note over CC,Hook: Stop hook: security-nudge fires<br/>if sensitive paths touched (1× per branch/day)

Reading the diagram: explicit user invocations are solid arrows (User -> CC), automatic hook firings are dashed Hook -> User returns, subagent delegation is one Task round-trip. Nothing in the maintenance layer (ADRs, session logs) is auto-fired - the agent recognizes the moment from the trigger-aware skill descriptions and the convention documented in AGENTS.md.

If you haven't run /stack-check in 30+ days, the SessionStart stack-freshness hook prints a one-line reminder (no network). The actual version check + AIDEV anchor health + AGENTS.md sanity audit only fires on explicit invocation.

For deeper walkthroughs see workflows/onboarding-a-legacy-repo.md, workflows/security-first-feature.md, and workflows/maintaining-as-it-grows.md.

flowchart LR
    Filip["Filip"] --> CC["Claude Code session"]
    Filip --> CX["Codex CLI session"]

    CC -- "reads" --> CMD["CLAUDE.md (1 line: @AGENTS.md)"]
    CMD -- "@import expand" --> AMD["AGENTS.md (canonical)"]
    CX -- "reads directly" --> AMD

    CC -- "loads skills from" --> SK["skills/"]
    CX -- "loads skills from" --> SK

    CC -- "hooks via" --> HK["hooks/hooks.json"]
    CX -- "hooks via" --> HKC["~/.codex/hooks.json (installed)"]
    HK -- "exec" --> SHELL["scripts/hooks/*.sh"]
    HKC -- "exec" --> SHELL

    CC -- "subagents" --> A1["agents/*.md (Markdown+YAML)"]
    CX -- "subagents" --> A2[".codex/agents/*.toml (TOML, generated)"]

Benchmarks

Does claude-leverage actually pay off? Controlled A/B benchmark on a real client codebase (~30k LOC Python web service). Two trees of the same codebase:

• BEFORE - commit predating claude-leverage adoption. No AGENTS.md, no AIDEV anchors, no per-directory docs, monolithic API surface.
• AFTER - current HEAD with the full in-repo artifact set: root AGENTS.md, per-directory AGENTS.md, AIDEV anchors throughout, ADRs, GLOSSARY.md, architecture.yml, per-domain router split, and the .claude-leverage-context-map.json manifest powering the context-surface PreToolUse hook.

Identical implementation task in both arms: add a new paginated HTTP endpoint following the conventions documented in each tree. Five Claude Opus 4.7 runs, plus one Claude Sonnet 4.6 run on a different task type (structured-logging migration) for cross-model sanity.

Headline (n=5, Opus 4.7)

Plus the separate Sonnet 4.6 run on a logging-migration task: −40 % cost.

Cheaper and the code is more maintainable

The cost number alone understates the value, because the AFTER agent does not get cheaper by being lazier. It gets cheaper by being dramatically more efficient at orientation, then often spends part of the saved budget producing richer, more convention-aware output:

• Less searching around - Grep counts drop −40 to −60 % per run, Glob often drops to zero. The agent knows where to look because per- directory AGENTS.md is auto-surfaced by the context-surface hook.
• Fewer files re-read before the first edit (orientation cost ↓ in 4 of 5 runs).
• But sometimes more output tokens produced. Run 4 AFTER generated +9.2 % output vs BEFORE, yet the total run still cost −9.5 % less.
• Wall-clock confirms the cost signal. With idle-pause time filtered out (gaps longer than 60 s ignored), AFTER also completes the task faster on average - mean active runtime 9.8 min BEFORE vs 8.6 min AFTER (−12.1 %). The time saving is smaller than the cost saving (−26.6 %) because part of the orientation budget gets reinvested into richer output, not pocketed.

That "more output" is the maintainability dividend. Across all 5 AFTER runs, the agent:

• Caught a documented load-bearing AIDEV-NOTE trap (a database-driver gotcha where the most natural parameter naming would silently produce wrong query results in production). The BEFORE agent caught it in 0 / 5 runs.
• Used the per-domain routers/ split instead of dumping the new endpoint into the monolithic API file.
• Used the LRU-cached SQL loader instead of the legacy direct-read form.
• In one run, additionally updated the API documentation file per the PR recipe documented in the per-directory AGENTS.md - a step the BEFORE agent had no way of knowing about.

The BEFORE agent's code worked. But it worked in the old style - no awareness of the conventions the rest of the codebase has since adopted. The next engineer (human or AI) opening that PR pays the cost later, in rework. That cost does not show up in the benchmark; it shows up six months later as drift.

Net effect: fewer tokens spent, and the tokens that are spent go into code that doesn't have to be rewritten later.

Spot-check: plugin v1.11.0 on Claude Opus 4.8 (n=1, expanding)

A newer, separate data point on the current plugin line and model — the headline chart above stays a clean Claude Opus 4.7 / n=5 set; this one is not folded into it. Same anonymised codebase, same endpoint-implementation task, Pure A/B (plugin OFF in BEFORE, ON in AFTER).

Both arms completed the task correctly. AFTER reached the same result with roughly half the orientation reading and zero grep/glob flailing — it went straight to the per-directory AGENTS.md and SQL docs instead of searching around. The documented parameter-naming gotcha bit neither arm this run: AFTER avoided it knowingly (and documented the reason inline for the next agent), BEFORE avoided it incidentally by following a local formatting convention — so no "trap-catch" win to claim here, just the cheaper-and-self-documenting path.

This is a single run and less clean than the headline set: part of BEFORE's higher cost is unrelated extra work the agent chose to do (it fixed a pre-existing cross-platform bug along the way), not pure orientation waste. The chart is built to grow — more Opus 4.8 / v1.11.0 runs append to it. Treat it as a first signal on the current line, not a result.

How it compares

claude-leverage and superpowers solve different problems - one is a guardrail + convention + memory layer, the other is a set of process-discipline skills. They're complementary; the table is a positioning aid, not a scoreboard.

They solve different problems - run both together.

What's inside

Why one repo for two tools

Per the research: AGENTS.md is the open spec both tools converge on. Claude Code reads CLAUDE.md natively but its @<path> import lets CLAUDE.md be a one-line redirect to AGENTS.md. Hook event vocabularies match between the two tools (PreToolUse, PostToolUse, SessionStart, Stop), so the same shell scripts work for both - only the trigger config differs. Subagents must be authored twice (MD+YAML for Claude, TOML for Codex), but scripts/gen-codex-agents.py keeps them in sync and CI fails on drift.

The full design rationale is in docs/adr/0002-agents-md-canonical-claude-md-import.md.

Honest history

This repo began as a v0.x experiment in routing work across Sonnet/Haiku subagents to save tokens. Opus 4.7's prompt caching inverted the economics - inline "read large, emit small" became cheaper than per-invocation dispatch - so the token-savings thesis stopped paying for itself, and v1.0.0 pivoted to what the data still supports: deterministic security hooks, on-demand skills, and self-maintaining conventions.

Full data + rationale: bench/archive-token-savings-thesis/, docs/adr/0001-pivot-from-token-savings-to-dev-stack.md.

Verify, update, uninstall

bash scripts/smoke-plugin.sh

/plugin install claude-leverage@filip-podstavec
/skill list                # confirm 15 skills appear
/agents                    # confirm security-reviewer + flaky-test-isolator
echo 'aws_key = "AKIAIOSFODNN7EXAMPLE"' > /tmp/test.txt && git add /tmp/test.txt
# Ask the agent to commit /tmp/test.txt - block-secrets-precommit should refuse.

/plugin marketplace update
/plugin update claude-leverage
/plugin uninstall claude-leverage@filip-podstavec

# Linux / macOS / WSL2
rm -rf ~/.agents/skills/claude-leverage
rm    ~/.codex/agents/security-reviewer.toml ~/.codex/agents/flaky-test-isolator.toml
# restore original ~/.codex/hooks.json (the installer leaves a .bak)
mv ~/.codex/hooks.json.pre-claude-leverage.bak ~/.codex/hooks.json 2>/dev/null \
   || rm ~/.codex/hooks.json
# Edit ~/.codex/AGENTS.md and delete the block between the two
# "# claude-leverage:" markers.

Remove-Item -Recurse -Force $env:USERPROFILE\.agents\skills\claude-leverage
Remove-Item -Force $env:USERPROFILE\.codex\agents\security-reviewer.toml,$env:USERPROFILE\.codex\agents\flaky-test-isolator.toml
$bak = "$env:USERPROFILE\.codex\hooks.json.pre-claude-leverage.bak"
if (Test-Path $bak) { Move-Item -Force $bak "$env:USERPROFILE\.codex\hooks.json" }
else { Remove-Item -Force "$env:USERPROFILE\.codex\hooks.json" }
# Then edit ~/.codex/AGENTS.md and remove the marker block.

License

MIT - see also CONTRIBUTING.md.