lazyplan (lpui) — v0.30.1

Plan work with your coding agent, in the terminal.

lazyplan is one shared plan for you and your agent. You get a fast keyboard screen. Your agent gets a simple command line. Plans, milestones, and tasks stay in one place instead of disappearing into chat. Read-only git and PR provenance shows where each one landed.

See it in action →

Install

pipx install lazyplan-tui
lpui --help

On Windows, use the pip backend:

pipx install --backend pip lazyplan-tui
lpui --version

The shared home is %LOCALAPPDATA%\lazyplan\ and the default --actor is %USERNAME%. Plan text is read as UTF-8 or UTF-16 and written as UTF-8, so PowerShell 5 exports round-trip.

Prefer a system package or the one-line installer? See install options.

Start

cd ~/my-plan
lpui                     # first run detects agents and creates the plan store
lpui plan add --title "my-plan" --why "reason" --what "scope"
lpui

Working with a team? lpui setup --placement repo keeps the plan in the repo.

Want demo data first? Run lpui seed.

Why it feels different

• One source of truth. The plan you see is the plan your agent reads. No copy-pasting context between chats.
• Made for focus. Plans stay as one-line summaries until you open them. Detail is there when you need it.
• Yours to keep. Local-first by default. Export or import any time. No account, no cloud, no lock-in.

New in 0.30

• Three themes, one key. t cycles Catppuccin Mocha, an OLED-black void, and Latte. LAZYPLAN_THEME picks one at launch, and every screen and chart follows it.
• A real GIT pane. Under the preview, the selected row shows its linked checkouts, branch and dirty state, ahead/behind counts, newest commits, and pull-request state.
• A preview that stays put. The status, title, and breadcrumb stay fixed while the reason, scope, next tasks, acceptance, and notes scroll beneath.
• One icon language and a calmer timeline. Plans, milestones, tasks, checkouts, commits, and pull requests share single-cell icons. The timeline card names the scoped plan, keeps every swimlane visible, and emphasizes the row under the cursor.

What you get

• A plan tree with progress at a glance, plus milestones and tasks underneath.
• A sticky preview of the reason, the next tasks, and what done means.
• A GIT pane with the checkout, commit, and pull-request context for the row.
• A read-only detail page for careful reading, with quick keys to edit and move work.
• Claim, blocked, gate, and attention state on the rows that need it.
• One place your agent can update while you keep the big picture.

Built to scale

The benchmark fixture holds 88 plans, 275 milestones, and 789 tasks. Query counts are deterministic and gated on Linux and macOS per change, with the same suite running on Windows nightly:

Linux timings from the final sweep. See performance for the method, budgets, and per-platform ceilings.

How it works

• Plans start as one-line summaries with progress. Open one to reveal milestones, then tasks.
• The side column previews the selected row: why, what, next tasks, and acceptance progress, with a GIT card for the linked checkout and commits.
• The timeline card at the bottom shows project, milestone, and task spans, with the scoped plan in its border.
• The bottom line shows the keys that work right now. ? opens help; c opens the command palette; t cycles themes.
• Your agent writes through the same command line. The screen updates as it works.

Everyday commands

lpui list                         # plans and progress
lpui plan show --id 1             # why, what, criteria, milestones
lpui task move --id 1 --to doing  # move work forward
lpui criterion tick --id 1        # tick the next acceptance item
lpui feed                         # recent activity

For your agent

The command line reads and writes the same plan, with porcelain rows, JSON, and clear exit codes:

lpui --actor helper --porcelain next
lpui --actor helper --porcelain note add --kind task --id 3 --text "Decision"
lpui --actor helper --porcelain list --tree
lpui --actor helper list --json

Use --porcelain in an active loop: writes answer with one tab-separated row and reads stay glyph-free. Use --json when you need full fidelity.

• Coordinate. next claims the first eligible task with a renewable lease, so two agents do not take the same work. Renew or release the claim, note handoffs, and block parked work with a reason.
• Prove. Relate each plan criterion to a proving task; lpui trace --plan 1 shows the evidence and lpui lint --plan 1 --strict gates the gaps.
• Collaborate. Comments and mentions live on plans, milestones, and tasks. lpui share --plan 1 produces a read-only HTML or JSON snapshot; lpui sync merges plans by stable UID without overwriting conflicts.
• Gate completion. task finish --require-pr --require-checks reads cached PR and CI evidence before done; --override REASON records an exception. A branch already recorded on another open task is rejected.
• Import work. lpui issue import brings GitHub issues (live) or Linear exports in as plans or tasks with source refs. Imports are one-way and re-import only refreshes source metadata.
• Use MCP. Hosts that support the Model Context Protocol can call lpui mcp for typed tools and resources; --read-only is available for reviewers.
• Watch flow. lpui stats --since 7.days shows WIP, cycle time, aging, stale work, and reopened rows. The TUI Attention filter surfaces the same risks, and / searches titles, descriptions, notes, comments, claims, blocked reasons, and issue refs.

In the screen, space marks rows for bulk move/block/release with one undo. After each commit, link it and move the task. lpui audit --since 7.days --strict turns the three accuracy metrics into a CI gate. lpui setup installs read-only lifecycle hooks for detected agents; lpui setup --no-hooks removes them.

The first run installs the agent skill. lpui setup --placement repo generates the full contract in the repo. See the usage guide for every command and limit.

Your data

Plans live in one local database: shared in your home by default, or inside a repo with lpui setup --placement repo. Back up with lpui export --format json; restore with lpui import --file. See data and backup.

Learn more

• Screenshots and quickstart
• Usage and CLI reference
• Performance and benchmarks
• Setup walkthrough
• Changelog
• Contributing (main is protected; open a PR)
• Releases · Issues

MIT licensed. This repo plans itself: run lpui list.