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 ~24 dimensions (Foundation / Why / What / In-code / Hygiene / Sync), reports a readiness level (L0–L4) with a local score trend, and names the gaps that matter most (--fix walks you through them).
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 16 skills and 3 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

What the Codex installer does

1. Resolves repo path into ~/.codex/hooks.json so security + nudge hooks fire in every Codex session globally.
2. Appends @<repo-path>/AGENTS.md to ~/.codex/AGENTS.md so the canonical guidance loads on every Codex session.
3. Copies .codex/agents/*.toml to ~/.codex/agents/.
4. Copies all 16 skills to ~/.agents/skills/claude-leverage/ so they work in Codex sessions exactly as in Claude Code.

Idempotent: re-running detects existing install via marker comments and overwrites in place. Atomic skill swap (staging dir + rename) so a copy failure mid-loop leaves the previous install intact.

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

Always-on safety - hooks, no setup, no model invocation

• block-secrets-precommit - refuses git commit if staged diff contains API keys / tokens / private keys (per-line allowlist via marker comment)
• block-dangerous-git - refuses git push --force, --no-verify, git reset --hard on protected branches
• ai-first-nudge - non-blocking: ≥50 net-new LOC without AIDEV-NOTE on non-test files OR new source-dir without AGENTS.md → one-line suggestion
• security-nudge - non-blocking Stop hook: ≥80 net-new LOC touching sensitive paths → suggests /security-review
• stack-freshness - non-blocking SessionStart: 30+ days since last /stack-check → one-line reminder via SessionStart additionalContext (no network)
• bare-repo-nudge - non-blocking SessionStart, two-branch nudge: (A) cwd is not a git repo AND not $HOME//tmp/system → reminder to git init + /init-repo; (B) cwd IS a git repo but root has no AGENTS.md / CLAUDE.md AND has a project marker file (package.json / pyproject.toml / Cargo.toml / go.mod / …) → reminder to /init-repo so the convention layer (AIDEV anchors, structured logging, …) actually gets loaded. One-per-day per cwd/repo-root.
• skill-cheatsheet - non-blocking SessionStart, gated on the repo having a claude-leverage: marker in AGENTS.md (i.e., the user has actively adopted the stack). Surfaces a compact list of high-value skills + triggers once per 14 days per repo, via SessionStart additionalContext. Mitigates the documented skill-auto-activation gap (description: | block scalars where the runtime parses only the first line). Override via CLAUDE_LEVERAGE_SKILL_HINT_DAYS (0 = disabled).
• overdue-todo-nudge - non-blocking SessionStart, network-free. Flags AIDEV-TODO / AIDEV-QUESTION anchors whose ISO-8601 deadline has already passed, via SessionStart additionalContext, once per repo per day. Source code only + first-token rule keep false positives near zero (skips the doc/template/test trees where example anchors live). The passive complement to /stack-check's on-demand anchor report. Opt-out: CLAUDE_LEVERAGE_SKIP_OVERDUE_TODO=1.
• context-surface - opt-in PreToolUse hook on Read|Edit|Write|MultiEdit. Reads a pre-built manifest at .claude-leverage-context-map.json (produced by scripts/build-context-map.py, or /refresh-context-map skill) and emits the AIDEV anchors that apply to the file the agent is about to touch via hookSpecificOutput.additionalContext. Cuts per-session token tax - agent no longer has to read every AGENTS.md preemptively to catch documented gotchas; the right anchors are surfaced at the moment of edit. Graceful no-op when manifest is missing. Verbose mode (CLAUDE_LEVERAGE_CTX_VERBOSE=1) also emits per-dir AGENTS.md chain
  • ADR refs. Opt-out: CLAUDE_LEVERAGE_CTX_DISABLE=1. See ADR 0008.

Security review - skill + dedicated subagent

• /security-review - audit current diff for OWASP-Top-10-shaped issues + package.json / requirements.txt typosquatting heuristic. Read-only Sonnet subagent returns Critical / Important / Nice schema with file:line. No dependency on any other plugin.

Repo-maintenance skills - invoke periodically

• /repo-map - refresh the architecture mermaid block in README between idempotent markers; optional dep-graph block via madge / pydeps