Skip to Content
TutorialsRun Ten Features at Once

Run Ten Features Without Chaos

Starting ten features is one loop. Keeping track of them is the hard part. In this tutorial you cap how many agents run at once, queue ten small features, then use the fleet tools to see what needs you, approve in a batch, retry what failed and pause new work.

Time: about 15 minutes of your own steps. You need: Shep set up in a repository, as in From zero to a merged PR.

Set a parallel limit and your defaults

shep settings workflow --push --pr --max-parallel 3

At most three features now run an agent at the same time; the rest wait in a queue. --push --pr makes every new feature push its branch and open a draft PR, so you don’t have to pass the flags ten times.

You should see Running at most 3 features in parallel. Check everything with shep settings show.

Queue ten features

Pick ten small, independent changes for your repository. For example:

for task in \ "add a 404 page" \ "fix the broken footer link" \ "add a dark mode toggle to the header" \ "add alt text to every product image" \ "show a spinner while the cart loads" \ "add a /health endpoint that returns uptime" \ "add a sitemap.xml" \ "rename the 'Buy' button to 'Add to cart'" \ "add a copyright line to the footer" \ "log every request with its duration" do shep feat new "$task" done

You should see ten ✓ Feature created blocks. The first three say Status: Implementation; the other seven say Status: Pending, because they are queued. Run shep feat ls to see all ten.

Each feature gets its own branch and worktree, so the ten agents never touch each other’s files or your checkout.

See the whole fleet

shep fleet status

shep fleet status in a terminal: "Shep Fleet Health" with Total Features 4, Cruising 1, Queued 0, Attention Needed 3, Failed 0, and Circuit Breaker Normal

  • Cruising: working without you.
  • Queued: waiting for a free slot. They start on their own, oldest first.
  • Attention needed: waiting for you, at a gate or with a question.
  • Failed: runs that stopped with an error.

The web UI shows the same counts in the Control Center header:

The fleet status bar: Fleet, 1 cruising, 0 queued, 3 need you, 0 failed, and a Triage (3) button

For a live view in your terminal, run shep tui. Features that need you are pinned at the top. See A terminal-only workflow with tmux.

You should see the numbers move as features finish: as one leaves its slot, a queued one starts.

Triage what needs you

shep fleet triage

shep fleet triage listing five P1 items: a blocking question from Add /health endpoint, two items for Add Stripe checkout and two for Add dark mode toggle, each with its reason, and for the plan gate the gate name and a suggested action

Triage lists only exceptions, by priority:

  • [P1] needs a decision: an approval gate, a blocking agent question, a merge conflict.
  • [P2] needs a retry or a look: a failed run, CI that used up its fixes.
  • [P3] is a warning, such as an agent that has been running for a long time.

In the browser, click Triage in the fleet status bar. The drawer has the same list, with Approve on gates and Retry on failed runs:

The Fleet triage drawer with five items, each tagged P1 and either Question or Approval gate, Approve buttons on the two approval gates, and an Approve all P1 button at the bottom

Answer questions where they’re asked: in the feature drawer, the Agent Questions page, or with the command shep feat status <id> prints. See Decisions & agent questions.

Approve in a batch

Your ten features run in fast mode, so each one stops at the merge gate once its PR is ready. Review the PRs first. Then approve one at a time:

shep feat approve <id>

Or every feature waiting at the merge gate at once:

shep fleet approve --gate merge

Approving a merge gate merges that feature’s PR. shep fleet approve always needs a scope: --gate prd, --gate plan, --gate merge, --all, or --low-risk, which approves only what your guardrail rules prove safe.

You should see ✓ Batch approved N of N candidate features. and the merged features leave the triage list.

Retry what failed

Look at why a run failed before you retry it:

shep feat status <id> shep feat logs <id>

Then restart every failed, crashed or stopped run:

shep fleet retry --failed

You should see each restarted feature listed. The command exits with code 1 if any of them couldn’t be restarted, and says why.

Pause new work

Say CI is down and you don’t want more agents opening PRs right now:

shep fleet pause --reason "CI outage"

You should see ✓ Fleet admission queue paused. Agents that are already running carry on; queued features stay queued and keep their place. shep fleet status now shows Admission Queue: PAUSED with your reason, the web status bar shows queue paused with a Resume button, and shep tui shows a banner.

When CI is back:

shep fleet resume

You should see ✓ Fleet admission queue resumed. Queued features start again as slots free up.

Clean up

Remove the limit, or keep it if it suits you:

shep settings workflow --max-parallel 0 # 0 = no limit, the default

Delete features you don’t want to keep with shep feat del <id>. It asks first, then removes the worktree and the branches and closes the PR.

Troubleshooting

  • Queued features never start. Check shep fleet status for Admission Queue: PAUSED and run shep fleet resume. To start one feature right away, ignoring the limit, run shep feat start <id> --force.
  • Circuit Breaker: TRIPPED. Several runs failed in a row. Shep reports this but doesn’t stop anything. Run shep fleet triage to find the common cause, and shep fleet pause while you fix it. shep fleet resume also resets the breaker’s count.
  • The triage Action: line doesn’t work. It suggests shep feat approve with the feature’s slug. If Shep answers Feature not found, use the id or an id prefix from shep feat ls instead.
  • Two features changed the same file. They can’t clash while they run, because each has its own worktree, but their PRs can still conflict when you merge them. A merge conflict shows up in triage as [P1].

What’s next