🪜 Ladder

Track every branch, stage, and alternative path in your AI pair-programming sessions.

When pair-programming with AI, every decision presents multiple paths. You pick one. The others vanish into scrollback. Three hours later, you realize you needed that other path too.

Ladder captures every branch, stages them by effort, and lets you climb back to any rung.

Install

pipx install ladder-cli

ladder is a CLI tool, not a library — pipx installs it into its own isolated environment and puts the ladder command on your PATH, so it can't collide with dependencies in whatever project you're standing in.

pip install ladder-cli also works if you're already inside a virtualenv. On a PEP 668–protected Python (Homebrew, some system installs), plain pip will refuse to install outside a venv — that's pip protecting itself, not a bug in this package; use pipx, a venv, or pip install --user instead.

Claude Code plugin (optional)

Skip the copy-paste system prompt — wire the ladder directly into Claude Code:

claude plugin marketplace add tanamsethi31/ladder
claude plugin install ladder@ladder

Claude sees the current ladder status automatically at session start and follows the ladder-tracking skill's rules (log new options as rungs, mark choices, show real command output) for the rest of the session — no manual ladder prompt paste needed. Requires ladder-cli installed and on PATH.

Quick Start

# 1. Initialize a ladder in your project
cd my-project
ladder init --project "My API"

# 2. Paste the system prompt into your AI assistant
ladder prompt

# 3. Start building — the AI populates the ladder automatically

# 4. Check your progress anytime
ladder status

How It Works

Ladder uses a Markdown + YAML file (.ladder/ladder.md) that both you and your AI can read and write:

---
project: My API
version: 1
---

## foundation

- [x] **R001** — Project scaffold → *small*
  - Context: Setting up the repo
  - Why: Everything builds on this

## core

- [ ] **R003** — User authentication → *medium*
  - Context: REST API auth
  - Why: Everything else depends on this
  - [x] JWT with refresh tokens
  - [ ] Session-based with Redis
  - [ ] OAuth2 social login
  - Blocked by: ~none~

Why this format wins:

• ✅ Git-friendly — clean diffs, full history
• ✅ AI-friendly — any LLM reads/writes markdown natively
• ✅ Human-friendly — open in any editor, understand in 30 seconds
• ✅ CLI-friendly — trivial to parse and render

Architecture

flowchart LR
    Dev["Developer"] -->|ladder init| Dir[".ladder/"]
    Dev -->|ladder prompt, or\nauto-injected by the\nClaude Code plugin| Prompt["System prompt / skill"]
    Prompt -->|read by| AI["Any AI assistant\nClaude, GPT-4, Cursor, Copilot"]
    AI <-->|reads / writes| File[".ladder/ladder.md\nMarkdown + YAML"]
    Dir --> File
    CLI["ladder CLI\nstatus · next · sprint · tree · export"] <--> File
    Dev -->|runs| CLI

No API calls, no server — the markdown file is the interface between you, the CLI, and whatever AI you're using. The Claude Code plugin is a thin, optional automation layer on top of that: same file, same CLI, it just auto-loads the rules instead of you pasting them.

Real output

This project dogfoods itself — its own .ladder/ladder.md tracks its own roadmap:

$ ladder status

🪜 ladder  v1  25 done · 0 active · 1 exploring · 0 open · 0 blocked

$ ladder next

🎯 Suggested next rungs

1. R021  Ambiguous pronoun references to rungs are unreliable  → medium
   Discovered via R008's A/B test: 'why is that still undecided' with multiple
   candidate rungs failed in both terse (derailed into logging talk, never
   answered) and full (confidently named the wrong rung) conditions. Not a
   terse-vs-full issue - a real, separate gap in resolving vague references
   when several rungs could match.

💡 `plugin` is 20/21 done — consider finishing it before moving on.

Small, well-understood work sorted ahead of bigger bets, automatically. R008 (terse vs. full SessionStart injection) is finally settled for real — a 12-trial controlled A/B test (same fixture, only the injected context differed) showed no behavioral cost to terse on the scenarios designed to expose one, and comparable tool-call counts either way. That test also surfaced R021, a genuine unrelated gap it wasn't looking for.

Commands

Why Ladder?

• Works with any AI — Claude, GPT-4, Cursor, Copilot, whatever
• No lock-in — your data is plain Markdown in your repo
• Auto-commits — optionally commits ladder changes to git
• Dependency aware — knows when a rung is blocked by another
• Effort-weighted — small/medium/large so you can plan sprints
• Zero-friction in Claude Code — the optional plugin auto-loads the rules and current status, no copy-pasting a system prompt every session

Contributing

1. Fork the repo
2. pip install -e ".[dev]"
3. pytest
4. Open a PR

Contact

Built by Tanam Sethi. Questions, bug reports, or feature requests — open an issue or reach out directly.

License

MIT — see LICENSE