Picking what's next
When you have a list of build packets and no strong feeling about which to start, type /retain:next in your coding agent (in Codex, $retain-next). Retain picks the next packet for the repository you are in, you confirm the pick, and the agent builds it in a worktree of its own. You never need to remember a packet's name.
It needs a checkout of the repository open in your agent. Outside one, it says so and stops.
What it looks at
The agent opens by saying what is covered: this repository's packets that are ready to build and that nobody is holding, and how many are free or being built by other agents. Packets of other repositories are not covered. Run it from a checkout of those instead.
A packet counts as ready to build when it is Ready to build, Planned or Building. Retain leaves out:
- Packets another build is holding. Several agents can work at once, and an agent that is building a packet claims it, so a second agent is never offered it.
- Packets waiting on a dependency. A packet whose dependency has no pull request yet can't be built from the right place. The agent says how many are waiting. See Dependencies and stacked pull requests.
- Packets whose tasks are all done. They look finished, and are counted as ready to curate. If that count is above zero, the agent suggests /retain:curate-work to archive or close them.
- Archived and dropped packets.
If nothing is left, the agent says why: none is ready, or every one is being built by someone else. Then it stops.
How Retain chooses
Retain ranks the packets from what it already knows. It favors a packet whose linked Thread is waiting on you, one that has started, and one whose requirements and tasks are already written. It ranks a packet lower when its pull request is open and in review, since that work is waiting on someone else. Among the rest, the one that has gone longest without a change comes first.
The agent shows you the best pick and two alternatives. Each has its name, title, state, how many tasks are done, and the reasons Retain gave in words, such as "6 of 9 done", "PR #412 is in review" or "Last changed 12 days ago". If the packet is linked to a Thread, you also see its subject. A packet that would stack on a dependency's branch says which.
Confirm the pick
Nothing is claimed or started until you choose. In Claude Code you pick from the list, with Retain's choice marked as recommended, each alternative, and None. In Codex the agent asks in plain text and reads back what it understood. None, or no answer, ends the run without changing anything.
The pick is a suggestion. Choose an alternative when you know better.
It builds in its own worktree
After you choose, the agent makes a separate worktree beside your checkout, on a new branch named for the packet, so your own work in progress is untouched. It follows your repository's own instructions for setting up a worktree when they have any. If you'd rather not have a worktree, it builds in place on a branch of its own. When the packet builds on a dependency with an open pull request, the worktree starts from that dependency's branch. Otherwise it starts from the default branch.
From inside that worktree it claims the packet, then builds it as /retain:apply would. See Explore, design, apply.
If another agent took the packet while you were choosing, the agent removes the worktree, says who holds it, and offers the next free packet. If a claim has run out, it asks before taking the packet over. A packet whose dependency is no longer ready is dropped from the pick and the agent chooses again.
You can follow the result on the packet's Build tab.
Need help?
Can't find what you're looking for? Contact our support team for a quick reply.
Contact Support