lean-and-mean

The problem

Coding assistants say and build too much: padded answers, plus helpers, options and abstractions nobody asked for, all of which must be read, reviewed and maintained. And they forget: every session starts blank, so yesterday's corrected mistake can happen again today.

lean-and-mean fixes both by writing a short set of instructions into root AGENTS.md. Codex loads it directly; Claude Code loads it through a one-line CLAUDE.md containing @AGENTS.md. The instructions are then present every session with no plugin code running.

What it does

The YAGNI ladder

Before writing code, the assistant stops at the first step that works:

1. Only maybe needed later? Skip it and say so.
2. Already in the project? Reuse it.
3. In the standard library? Use it.
4. Native to the platform (browser, OS, framework)? Use it.
5. An installed dependency does it? Use it.
6. Fits in one line? One line.
7. Otherwise, the smallest new code that works.

Minimal never means careless. It never cuts input validation at trust boundaries, error handling that prevents data loss, security, accessibility, or anything you asked for. Also:

• Root cause. Bugs are fixed at the shared place they come from, not in every caller.
• Labeled shortcuts. A deliberate shortcut gets a comment such as // lean: up to 1,000 rows, stream if larger; /lean-and-mean debt lists them all.
• One runnable check for logic with branches, loops, parsing, money or security.
• A skipped note. After code, at most three lines on what was left out and when to add it.

An AGENTS.md that maintains itself

• Rules. Each correction becomes one dated line, capped at 15 so the list stays readable.
• Next and Todo. ## Next names the very next task; ## Todo is a short prioritized backlog. History stays in git log.
• Fixed layout. Operating Mode, Project & Stack, Commands, Architecture & Layout, Conventions, Rules, Next, Todo, Notes & Pointers, always in that order.
• 250-line cap. The file is resent on every request, so overflow moves to linked agents-<category>.md files.

Commands

Claude Code plugin installs spell them /lean-and-mean:lean-and-mean and /lean-and-mean:endsession; Codex uses $lean-and-mean and $endsession.

What happens automatically

A session-start hook stays silent unless:

• The instructions aren't in AGENTS.md. It loads them for this session and suggests /lean-and-mean to make them permanent.
• A cleanup is due: the plugin was updated, the file passed 250 lines, the last /endsession flagged a review, or CLAUDE.md holds more than the stub (the cleanup moves it into AGENTS.md). The assistant runs the cleanup before your first task.
• No advisor is set (Claude Code only).

The session band mod

Claude Code only. The plugin ships a mod: a small function-hooks module (hooks/register.tsx) that Claude Code loads with the plugin and runs inside the session. It draws a row above the prompt:

tasks 2/3   [ hide tasks ]  [ end session ]
  ✓ Fix the login redirect
  ✓ Add a test for it
  ☐ Update the changelog

• Task checklist. After each answered turn, Haiku adds the tasks you asked for and ticks the ones the reply shows finished. hide tasks folds the list to its count.
• End session button. Runs /lean-and-mean:endsession. When every task is done it turns primary, a toast appears, and your next prompt tells Claude to suggest wrapping up first.
• Auto end. The 1-hour prompt cache restarts with every request. With 5 minutes left after real work, the mod runs /endsession itself (commit and push included), so the handoff is written before the next turn has to re-read the whole context at full price.
• Cost and off switch. One low-effort Haiku call per answered turn, capped at 8 seconds. Turn it off in /config → Session band. Codex ignores the mod.

How the mod works, including the optional status line with a cache countdown.

Extras

Each extra is covered in full in the guide.

• dashboard-builder (Claude Code). A subagent for any task over about five steps or 30 minutes; its description tells Claude to use it, and you can ask for it by name. It builds .dashboard/index.html, a self-refreshing page with tasks, open questions, deliverables and anything stuck. Claude updates it after every step, and a question that needs you is listed with the default Claude is proceeding on. Style is asked once and remembered. How the dashboard works.
• explainer (Claude Code). A subagent that writes .pages/<slug>.html, a self-contained page with inline SVG diagrams, when an answer runs past a screen, compares options, or will be revisited. How the explainer works.
• Status line (Claude Code). extras/statusline.sh adds context use and a prompt-cache countdown to your status line; you copy it in yourself. Setup.
• Advisor. Claude Code can consult a stronger model before a plan, on a recurring error, and before declaring done. Enable once with /advisor fable or /advisor opus. Its cost grows with session length, one more reason to use /endsession. Advisor and effort settings.
• Effort. Run the main session at high effort and hand routine subagent work to Sonnet at medium effort.
• typesafe-ai. TypeSafe AI's skill for building features on their Jev model, which turns text and app state into typed yes/no and pick-one answers. Routed through OpenRouter with OPENROUTER_JEV_API_KEY. Disabled for now: the assistant won't load it on its own. What Jev is for.

Why it pays off

Measured from 63 sessions and 5,197 requests (2026-09-03 to 2026-10-03) at API list prices, mostly on Opus 5, whose cache reads cost $0.50; on Opus 5.5 at $0.20 the absolute figures are lower. Every tool call resends the whole context, so cost scales with requests × context size. See why sessions should be short for the full model.

Install

Claude Code

claude plugin marketplace add spinlockdevelopment/lean-and-mean
claude plugin install lean-and-mean@lean-and-mean

Restart Claude Code and run /lean-and-mean:lean-and-mean once in each project to write AGENTS.md and the CLAUDE.md stub. Until then the hook loads the instructions each session and reminds you.

Codex

codex plugin marketplace add spinlockdevelopment/lean-and-mean
codex plugin add lean-and-mean@lean-and-mean

Start a new session at the project root, trust the SessionStart hook when prompted, and run $lean-and-mean once.

No plugin support, or want bare command names? See manual install.

Turning it off

Disable the plugin and delete the ## Operating Mode section from AGENTS.md. The instructions live in the file, so disabling alone isn't enough.

Raw instructions

The plugin is plain text the model follows:

• operating-mode.md — the block written into AGENTS.md
• lean-and-mean/SKILL.md — setup, cleanup and file structure
• endsession/SKILL.md — the session handoff

Also bundles typesafe-ai, TypeSafe AI's skill for the Jev model, routed through OpenRouter. Copyright and credit: TypeSafe AI (MIT). lean-and-mean is MIT licensed.