Installation

Installation

As a Claude Code plugin

The repository is a plugin and its own marketplace.

claude plugin marketplace add arnelirobles/lean-agent
claude plugin install lean-agent@lean-agent

That gives you:

Part	What it is
method skill	The condensed rules. The agent loads it when it plans, files, reviews or finishes a batch. You do not call it.
/lean-agent:shape-ticket	Writes an issue in the agent-ready shape. See Shaping a Ticket.
/lean-agent:adversarial-review	The critic. See Adversarial Review.
/lean-agent:lean-retro	The retro. See Retro.
bin/	Every script on the agent's PATH while the plugin is enabled. See Scripts.
brain	A local SQLite list of what is open: failures, deferred minors, questions, blockers, running agents, plus the test queue. See Brain.
test-phase	Drains the test queue one job at a time, on this machine and on any remote hosts. See Test Queue and Remote Lanes.
brain MCP server	bin/brain-mcp, registered by the plugin, gives a session brain as tools. See Brain MCP.
Hooks	Three that block, the rest add a note. See Hooks.

The Lean Brain VS Code extension is separate. It shows the brain database and the queue in the editor. See Lean Brain Extension.

Updating

Claude Code updates an installed plugin only when its version changes.

claude plugin update lean-agent@lean-agent

Settings

Settings go in the env block of your Claude Code settings file. None are required. Settings lists them all.

{
  "env": {
    "LEAN_MODEL_CHEAP": "sonnet",
    "LEAN_MODEL_STRONG": "opus",
    "LEAN_MODEL_FAST": "haiku"
  }
}

With the plugin on, "attribution": {"commit": "", "pr": ""} in your settings is not needed, because the public-text.py hook blocks the trailer anyway. Setting both is harmless.

Without the plugin

The scripts at the repository root are links into bin/, and each runs by itself. Clone the repository and call them by path.

git clone https://github.com/arnelirobles/lean-agent
python3 lean-agent/asset-provenance.py .

The skills also work copied by hand: put skills/adversarial-review into .claude/skills/ in a repository, or into ~/.claude/skills/ to use it everywhere.

Requirements

• Python 3.9 or newer for the hooks. They use the standard library only.
• gh for pr-blockers.sh, and gh plus jq for retro-signals.sh.
• Linux or macOS. The scripts run on macOS's stock bash 3.2, except heavy.sh, which needs util-linux flock and /proc and refuses to run without them.

Per-repository files

These live in your repository, not in the plugin.

File	Used by
.lean/needs-review.rules	needs-review.sh. Start from examples/needs-review.rules.
.lean/top-level-md.allow	check-top-level-md.sh, one allowed root Markdown name per line.
docs/review-rules.md or .claude/review-rules.md	The critic. skills/adversarial-review/review-rules.example.md shows the shape.
.lean/lessons.tsv	Written by lesson-log.py, read by the retro. Kept out of commits through .git/info/exclude.

Per-machine files

File	Used by
~/.local/share/lean/brain.db	brain, test-phase, brain-mcp and the extension. Move it with LEAN_BRAIN_DB.
~/.config/lean/remotes.ini	test-phase, to drain the queue on SSH hosts. See Remote Lanes.