whatsnext
One plan, one next step, for every coding agent.
whatsnext is a plugin for Claude Code and Codex. It keeps a plan checklist, check-offs and a short resume note as plain files in your repository, so a new session, or a second agent, starts from where the last one stopped.
Status: 0.4.0. See New in 0.4.0.
MIT license · Python 3.9+, standard library only · no database, no background process
Install
Claude Code:
claude plugin marketplace add archid21/whatsnext
claude plugin install whatsnext@whatsnext
Codex: from a checkout, run python3 skills/whatsnext/scripts/whatsnext.py install-hooks, then review the new hooks in Settings > Hooks (desktop) or /hooks (CLI).
Key steps
- Say "set up whatsnext in this repo" and make a plan.
- Work. Say "wrap up" before you step away or clear the chat.
- Come back and say "what's next?". You pick up where you left off.
When an item is finished, say "mark P-13 done". It is ticked only if its test command passes.
Features
| Feature | What it does |
|---|
| Set up your plan | PLAN.md, a checklist in your repo. "what's next?" shows the first open item. |
| One status call | "what's next?" and "where did we leave off?" run whatsnext status: the current item, the handoff, the ready items and any warnings. |
| Start work | "start P-13" asks a few questions, then you run all steps or one at a time. Another agent or session cannot take an item you hold. |
| Two chats in one folder | When another session has work in progress here, Start asks whether to use a new worktree. Each chat resumes its own item. |
| Change the plan | "add an item", "drop P-16", "move P-14 to Later", or import a plan from any spec or task file. |
| Mark done with proof | The item is ticked only when its test command exits 0. Otherwise it stays open with the last 20 lines of output. |
| Review before done | An item with review: required waits for your plan review after its check passes. |
| Reuse a passing run | plan done --verify reuses a passing run of the same check on unchanged code. |
| Start fresh after wrap-up | After "wrap up", one click compacts here or copies a prompt for a new session. |
| Save and resume | "wrap up" writes your goal, next step and decisions to docs/project/HANDOFF.md. A short resume note loads at session start, after /clear and after a compact. |
| Smart compact | The /compact text is built from your handoff, so the summary keeps your goal. |
| Auto wrap-up | Opt-in. After 45 idle minutes, your handoff is saved before Claude Code's own idle compact. |
| Task progress files | One file per task: goal, what is done, the exact next step, and a journal of commits and files changed. |
| Tips | Claude Code only. A hint bar teaches the phrases above, one at a time. |
| Claude Code and Codex | Both agents read and write the same plain files. Switching between them is experimental. |
Every feature, how it works, its value and the release that added it: docs/FEATURES.md.
New in 0.4.0
- Review before done: an item with
review: required is not ticked when its check passes. It shows awaiting review until you run plan review <id> (or reject it with a reason).
- Reuse a passing run:
plan test <id> runs the saved check. plan done --verify reuses a passing run of the same command on the same code, so a long suite runs once. --fresh forces a new run.
- Edit and reopen:
plan edit keeps an item's id. plan reopen keeps the old evidence and asks for a fresh check.
- Start fresh after a wrap-up: the band above the prompt offers Compact and continue here or Copy for new session. Other plugins can call
fresh-instructions for the same choice.
- Resume one task:
progress resume <id> prints the note for one task from its newest handoff.
- Better handoffs and compacts:
HANDOFF.md lists files, links and skills used. After a compact, the resume note says how many plan steps the summary kept.
- More checks and output:
plan check flags done items whose branch is not merged into main. progress pr-body <id> prints a PR description from recorded facts.
New in 0.3.1
- Star ask: once, after your first verified
mark done, the tip band asks for a GitHub star. One click stars it with your gh sign-in; No thanks hides it for good. With rightsize installed, one ask covers both.
New in 0.3
- One status call:
whatsnext status answers "what's next?" and "where did we leave off?": the current item, the handoff, the ready items and the warnings.
- Two chats in one folder: Start asks for a new worktree when another session has work in progress here. Claims and the active task belong to a session.
- Your own note after
/clear: a recent Task: none handoff from this branch says "read it first".
- Safer plan: claims are atomic locks, a dropped id is never reused, and
plan check reports blocked-by cycles.
- Simpler wrap-up in Claude Code: the reply ends with one
/compact hint, and a recent handoff steers a new session.
New in 0.2
- Edit and import the plan:
plan add, plan drop and plan move, and import a plan from any spec or task file.
- Run the whole item: at start, choose to run all steps, then verify and mark done.
- Stricter proof:
--verify runs the item's saved test command. A different command needs your approval, recorded with the evidence.
- Better resume: after a compact, the resume note repeats your latest request.
plan next puts the work in progress in this checkout first.
- Codex continuity:
wrap up, forked chats, interruptions and session end now work in Codex. doctor shows which hooks each agent has actually run.
- Opt-in auto wrap-up, a tip bar and a welcome table after install.
New here? Read the user guide: what to say to save a session, resume it, pick work and mark it done.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
