Step away for lunch. Pick up where you stopped.
whatsnext keeps a plan checklist, check-offs and a short resume note as plain files in your repo. A new session, or a second agent, starts from where the last one stopped, in Claude Code or Codex.
PLAN.md, a handoff note, progress and journal files) and runs hooks at session start and end. Commit your work first, and review what it writes. Using more than one agent on a plan is experimental. If something breaks, open an issue with what you ran and what you saw.
The problem
A coding agent forgets between sessions. So you pay in one of three ways:
- You re-explain. What was done, what is left and which branch it lives on.
- Two agents take the same item. Nothing says who has it.
- "Done" is a claim. The agent says the tests pass, and no one ran them.
A compact does not fix this. It keeps whatever the model thinks matters, which may not be your goal.
What you get
- A plan every agent reads.
PLAN.mdis a checklist in your repo.plan nextshows what is next.plan startasks a few questions first and refuses an item another agent has checked out. A claim is a note, not a lock: two agents asking at the same moment might both get it. - "Done" means a command passed.
plan done P-13 --verify "<cmd>"runs your command. Exit 0 ticks the item. Anything else leaves it open and saves the last 20 lines of output. An item no command can check is ticked with--evidenceand shows asdone*, so you can tell the two apart. - Resume where you stopped. At session start, after
/clearand after a compact, a note of at most 1,200 characters says what is done, what is next, which test command to run and what changed since. It warns when it is over 7 days old. - A handoff on one prompt. Say "wrap up". The agent writes the goal, next action, decisions, constraints and open blockers to
docs/project/HANDOFF.md. The next session reads it first, but only when the note is its own or belongs to its task, so two agents in one repo do not read each other's. - A compact that keeps your goal.
compact-instructionsbuilds the/compacttext from that handoff, so the summary keeps what you wrote down. - Works in Claude Code and Codex. Both read and write the same plain files. Switching agents on one plan has not been extensively tested.
| Without whatsnext | With whatsnext | |
|---|---|---|
| Start of a session | You retype the context | A short resume note |
| Saying "done" | A claim | A command passed, or it shows done* |
| Two agents, one plan | They may take the same item | The second is told who has it |
| Compact | Keeps what the model picks | Keeps your goal, next action and constraints |
How it works
- Hooks run. At session start, after
/clearand after a compact, a hook prints the resume note. Other hooks record plan-mode plans and add one line per session event to a facts journal. Claude Code and Codex call the same script. - The script saves state as plain files. The plan is
PLAN.md. Progress per task and the journal live indocs/project/progress/. The handoff note isdocs/project/HANDOFF.md. Read and edit any of them. - The next session reads them. It starts from the files, not from a retelling.
Better with rightsize
whatsnext works alone. With rightsize, it does more: rightsize sends "wrap up" once before a big session's cache goes cold, and its Compact now button runs /compact with whatsnext's text. rightsize decides when. whatsnext decides what to keep. This needs rightsize 0.9.0 or later.
Privacy
- No model calls from hooks. The facts journal and resume note use no model. "Wrap up" uses your open session to write the note.
- State stays in your repo.
- No network calls of its own. whatsnext runs
gitfor history.plan done --verifyruns your test command, which may use the network. - It never pushes and never creates a remote repository.
Known limits
- Using more than one agent on a plan is experimental.
- Claims are notes, not locks.
- In Codex's default sandbox, a claim is written to
.whatsnext/claims/, so another worktree does not see it. - Agents can skip the commands.
plan checkfinds items ticked without evidence. - Codex support is new. Expect rough edges.
Install
You need Python 3.9 or later. whatsnext uses only the standard library.
In Claude Code, run these two commands:
/plugin marketplace add archid21/whatsnext
/plugin install whatsnext@whatsnextThen, in your project, say set up whatsnext. It shows what init would write and waits for your OK. init changes only PLAN.md, .whatsnext/, one line in .gitignore and one marked block in AGENTS.md. init --undo removes the block.
To try it, say wrap up, then start a new session.
Codex
Codex hooks need Codex 0.145.0 or later. Run whatsnext install-hooks, then trust the hooks in Codex's /hooks.
Ask Claude to install it
Paste this into Claude Code.
Install the whatsnext plugin from GitHub for me. Run these two commands in the terminal:
1. claude plugin marketplace add archid21/whatsnext
2. claude plugin install whatsnext@whatsnext --scope user
Tell me if either one fails and why. When both succeed, tell me to start a new session. Then tell me to commit my work in the project I want to use whatsnext in, and to say "set up whatsnext" there. It shows what it will write and waits for my OK.Claude asks your permission before it runs each command. When it is done, start a new session.
Work in progress
whatsnext is experimental, at version 0.1.0. It may have bugs, and it is tested only on the versions named above. Report problems on GitHub, or email hello@aivalue.blog. This is an independent project, not made or endorsed by Anthropic.