# LeanLane

**Stop AI agents from over-building.** Decision ladder, diff scoreboard, prune review, MCP tools, and installable agent skills — local-first, measurable, and safe.

Part of **[Talocode](https://talocode.site)**. Optional cloud routes under `/v1/leanlane/*`.

| | |
|--|--|
| **npm** | `npm install -g @talocode/leanlane` |
| **PyPI** | `pip install talocode-leanlane` |
| **CLI** | `leanlane` |
| **MCP** | `leanlane mcp` |
| **Cloud** | `https://api.talocode.site/v1/leanlane/*` |
| **Auth** | `TALOCODE_API_KEY` (cloud only) |
| **Repo** | https://github.com/talocode/leanlane |
| **License** | MIT |

## Why LeanLane?

Coding agents often solve a ticket by inventing frameworks: new packages, wrappers, abstractions, and hundreds of lines nobody asked for. That burns tokens, slows reviews, and leaves brittle code.

**LeanLane** puts a senior “write less” discipline into the loop:

1. **Decide** before writing — climb a fixed ladder (skip → reuse → stdlib → native → installed dep → one-liner → minimum new code).
2. **Score** the diff — LOC, new files, dependencies, abstraction signals, grade A–F.
3. **Review** for over-engineering — delete-list, not vibe comments.
4. **Rules / skill** — always-on agent instructions with modes (`lite` / `full` / `ultra` / `off`).
5. **Safety floor** — never cut validation, security, accessibility, or understanding for fewer lines.

Open tool people can trust. Hosted power when teams want shared scoreboards and API metering.

## Install

```bash
npm install -g @talocode/leanlane
# or
npx @talocode/leanlane --help

pip install talocode-leanlane
```

## Quickstart (CLI)

```bash
# What should the agent do *before* coding?
leanlane decide --task "add a date picker to the form"

# Score the working tree diff
leanlane score --git

# Review a file for bloat
leanlane review --file src/app.ts

# Export always-on rules into the repo
leanlane rules --mode full --out AGENTS.leanlane.md

# Export SKILL.md for agent hosts
leanlane skill --mode full --out skills/leanlane/SKILL.md

# Default mode for new sessions
leanlane mode set full

# MCP stdio server for agents
leanlane mcp
```

### Example: decide

```bash
leanlane decide --task "add a date picker" --mode full
```

Returns a recommended rung (often `native_platform` for date pickers), rationale, full ladder, safety floor, and agent instructions.

### Example: score a diff

```bash
leanlane score --diff "$(git diff HEAD~1)" --mode full
```

```json
{
  "ok": false,
  "score": 42,
  "grade": "D",
  "metrics": {
    "filesTouched": 4,
    "linesAdded": 280,
    "newDependencies": 1,
    "newFiles": 2
  },
  "findings": [ ... ]
}
```

Exit code `2` when the score fails the mode threshold (useful in CI).

## TypeScript SDK

```ts
import {
  decide,
  scoreDiff,
  reviewCode,
  getRuleset,
  createLeanLaneClient,
} from '@talocode/leanlane'

const plan = decide({
  task: 'add a date picker',
  nativeCandidate: '<input type="date">',
})

const score = scoreDiff({
  diff: await Deno.readTextFile('patch.diff'), // or any unified diff string
  mode: 'full',
})

const client = createLeanLaneClient() // uses TALOCODE_API_KEY for cloud
await client.health()
```

Local engine calls need **no API key**. The client is for optional Talocode Cloud routes.

## Python SDK

```python
import os
from leanlane import LeanLaneClient, decide, score_diff

print(decide(task="add a date picker"))
print(score_diff(diff=open("patch.diff").read()))

client = LeanLaneClient(api_key=os.environ.get("TALOCODE_API_KEY"))
print(client.health())
```

## MCP

```bash
leanlane mcp
```

Exposes:

| Tool | Purpose |
|------|---------|
| `leanlane_decide` | Ladder decision before coding |
| `leanlane_score_diff` | Score unified diffs |
| `leanlane_review` | Over-engineering review + delete-list |
| `leanlane_rules` | Mode ruleset markdown |
| `leanlane_health` | Version + capabilities |

Example host config (stdio):

```json
{
  "mcpServers": {
    "leanlane": {
      "command": "leanlane",
      "args": ["mcp"]
    }
  }
}
```

## Modes

| Mode | Behavior |
|------|----------|
| `off` | No lean pressure |
| `lite` | Prefer reuse/stdlib; fail only on high/critical bloat |
| `full` | Default ladder + fail on high findings or weak score |
| `ultra` | Aggressive minimalism; medium findings fail |

```bash
export LEANLANE_MODE=full
# or
leanlane mode set ultra
```

## Safety floor (never cut)

- Input validation at trust boundaries  
- Error handling that prevents data loss  
- Security-sensitive paths  
- Accessibility for user-facing UI  
- Understanding the problem before shrinking the diff  
- One runnable check for non-trivial logic  

## Cloud routes (optional)

Base: `https://api.talocode.site`

| Path | Credits (indicative) |
|------|----------------------|
| `GET /v1/leanlane/health` | 0 |
| `GET /v1/leanlane/pricing` | 0 |
| `GET /v1/leanlane/capabilities` | 0 |
| `POST /v1/leanlane/decide` | 2 |
| `POST /v1/leanlane/score` | 5 |
| `POST /v1/leanlane/review` | 5 |
| `POST /v1/leanlane/rules` | 1 |
| `GET /v1/leanlane/skill` | 1 |

Auth: `Authorization: Bearer $TALOCODE_API_KEY` or `X-Api-Key`.

## Agent skill

```bash
leanlane skill --out skills/leanlane/SKILL.md
```

Compatible with Codra, Cursor-style skill folders, Claude Code-style skills, and OpenCode-style workflows. Copy into your agent’s skills directory or keep under `.agents/skills/leanlane/`.

## CI gate example

```bash
leanlane score --git --mode full || exit 1
```

## Related packages

| Package | Install |
|---------|---------|
| LeanLane (this) | `npm i @talocode/leanlane` · `pip install talocode-leanlane` |
| VerifyLane | `npm i @talocode/verifylane` · `pip install talocode-verifylane` |
| PolicyLane | `npm i @talocode/policylane` |
| StyleLane | `npm i @talocode/stylelane` |
| EvalLane | `npm i @talocode/evallane` |
| TraceLane | `npm i @talocode/tracelane` |
| GateLane | `npm i @talocode/gatelane` |

## Talocode ecosystem

| Product | Role |
|---------|------|
| **[LeanLane](https://github.com/talocode/leanlane)** | **(this package)** stop agent over-building |
| **[VerifyLane](https://github.com/talocode/verifylane)** · `pip install talocode-verifylane` | Deterministic code verification |
| **[PolicyLane](https://github.com/talocode/policylane)** | Allow/deny + redaction |
| **[StyleLane](https://github.com/talocode/stylelane)** | Constitution packs |
| **[EvalLane](https://github.com/talocode/evallane)** | Assertion eval suites |
| **[TraceLane](https://github.com/talocode/tracelane)** | Agent run tracing |
| **[RetryLane](https://github.com/talocode/retrylane)** | Retries & circuit breakers |
| **[PromptLane](https://github.com/talocode/promptlane)** | Prompt versioning |
| **[HandoffLane](https://github.com/talocode/handofflane)** | Schema handoffs |
| **[GateLane](https://github.com/talocode/gatelane)** | MCP gateway |
| **[SearchLane](https://github.com/talocode/searchlane)** · `pip install talocode-searchlane` | Agent web search |
| **[ContextLane](https://github.com/talocode/contextlane)** · `pip install contextlane` | Shared agent context |
| **[MemoryLane](https://github.com/talocode/memorylane)** | Agent memory |
| **[Tera](https://github.com/talocode/tera)** · `pip install talocode-tera` | Capability API |
| **[Codra](https://github.com/talocode/codra)** · `pip install talocode-codra` | Coding agent |
| **[StackLane](https://github.com/talocode/stacklane)** · `pip install talocode` | Keys, wallet, metering |
| **[Tradia](https://github.com/talocode/tradia)** · `pip install tradia` | Trading agents |
| **[ScreenLane](https://github.com/talocode/screenlane)** · `pip install talocode-screenlane` | Screen context |
| **[XSearchLane](https://github.com/talocode/xsearchlane)** · `npm i @talocode/xsearchlane` | X search |
| **[XProLane](https://github.com/talocode/xprolane)** · `pip install talocode-xprolane` | X pro workflows |
| **[Agent Browser](https://github.com/talocode/agent-browser)** | Browser automation |
| **[ClipLoop](https://github.com/talocode/cliploop)** | Clip / media loops |
| **[InvoiceLane](https://github.com/talocode/invoicelane)** | Invoicing |
| **[GeoLane](https://github.com/talocode/geolane)** | Geo utilities |
| **[DevTool](https://github.com/talocode/devtool)** · `pip install talocode-devtool` | Dev tooling |

More: [github.com/talocode](https://github.com/talocode) · [talocode.site](https://talocode.site) · [docs.talocode.site](https://docs.talocode.site)

## License

MIT © Talocode