Skip to Content
Core ConceptsAgent Activity & States

Agent Activity & States

For any feature, Shep can tell you one thing at a glance: is its agent working, blocked on you, waiting, done, or failed, and why. The same answer appears on the web’s Agent activity page, in a feature’s drawer, in shep feat status, in the terminal console, and to other tools over MCP and A2A. It is worked out from the same data everywhere, so the surfaces never disagree.

The five states

StateMeaning
workingAn agent is executing
blockedSomeone has to act: an approval gate, an agent question, or a review. Shown as Needs you in the web UI
waitingNot started: queued for a slot, deferred, or waiting on a parent feature
doneFinished, or archived
failedThe run failed, was interrupted or cancelled, or its process died

An open agent question makes a working or waiting feature blocked, with reason agent-question.

Reasons

Each state comes with a reason, the rule that decided it. shep feat status prints the reason as a sentence; --json and the APIs give the key.

ReasonShown asState
agent-runningThe agent is workingworking
in-progressIn progressworking
approval-gateWaiting for your approvalblocked
agent-questionThe agent asked a questionblocked
awaiting-reviewIts pull request waits for your reviewblocked
plan-task-in-reviewA plan task waits for your reviewblocked
queued-for-capacityQueued until a slot under the parallel-feature limit frees upwaiting
deferredDeferred: no agent has started yetwaiting
waiting-on-parentWaiting for its parent feature to finishwaiting
run-completedFinisheddone
maintainedFinished; in maintenancedone
plan-tasks-doneEvery plan task is donedone
archivedArchiveddone
deletingBeing deleteddone
run-failedThe run failedfailed
run-interruptedThe run was interruptedfailed
run-cancelledThe run was cancelledfailed
process-diedThe agent process stopped unexpectedlyfailed

queued-for-capacity comes from the parallel-feature limit, deferred from shep feat new --pending, and waiting-on-parent from shep feat new --parent. A failed feature is recovered with shep feat resume <id>, Retry in the drawer, R in the terminal console, or shep fleet retry --failed for all of them.

In the web UI

Agent activity in the sidebar (/activity) lists every feature’s agent with its state, why, what the agent is asking (if anything), the repository and phase, and a link to the next step, such as Review and approve or Open to resume. Chips at the top count each state. Finished features are hidden until you turn on Show finished. The sidebar link carries a badge with the number of blocked features.

A feature’s drawer opens on its Overview tab with an Agent status card: the state, why, what the agent asks, the phase, and what to do next.

The feature drawer for "Add Search Filters To The Orders Page": the Agent status card shows Needs you, Why: Waiting for your approval, Asks: Should the filters persist in the URL so a filtered view can be shared?, Phase: merge, Next: Approve or reject in its review tab

Notify me

On the Agent status card, Notify me watches the feature for you. When it needs you, finishes or fails, you get a toast and a browser notification. Stop ends the watch.

The Agent status card of a waiting feature while Notify me is on: "Watching — you'll be notified when it needs you, finishes or fails", with a Stop button

Approve, reject and answer stay where they are: the drawer’s action bar and the Agent Questions inbox, which the next-step links open.

From the CLI

shep feat status

shep feat status <id> shep feat status <id> --json
Add A Login Page With Email And Password blocked Why Waiting for your approval Phase merge Run waiting_approval ID 7a8252ce-8c09-413a-b1dc-e22e7a082e32 Next shep feat approve 7a8252ce | shep feat reject 7a8252ce

<id> is a feature id or id prefix. When the agent is asking something, an Asks line shows the question; a failed run shows its Error, and a feature with a PR shows the PR. With --json you get the fields for scripts:

$ shep feat status 7a8252ce --json | jq '{state, reason, phase, actions, version}' { "state": "blocked", "reason": "approval-gate", "phase": "merge", "actions": ["approve", "reject"], "version": 1793204235588 }

version increases whenever the activity changes. If you poll, compare the state too: answering a question can lower the version once between two separate reads.

To list every feature, use shep feat ls, the Agent activity page, or the terminal console.

shep feat wait

shep feat wait blocks until a feature’s agent needs someone, finishes or fails, and then prints its status. Use it in scripts, or to hand control back to another agent at the right moment.

shep feat wait <id> # until blocked, done or failed shep feat wait <id> --until done --timeout 3600 # only done, give up after an hour shep feat wait <id> --until working,blocked --json
OptionMeaning
--until <states>Comma-separated states to wait for: working, blocked, waiting, done, failed. Default blocked,done,failed
--timeout <seconds>Give up after this many seconds. Without it, waits until a state is reached or you press ctrl+c
--jsonPrint the result as JSON (outcome plus the activity)

The exit code tells a script how the wait ended:

Exit codeOutcome
0Reached one of the states
1No feature with that id or prefix
2Timed out; the output says the state it’s still in
3The id prefix matches more than one feature
130Interrupted with ctrl+c
shep feat new "Add rate limiting to the public API" --repo . # … copy the id it prints … if shep feat wait 7a82 --timeout 1800; then shep feat status 7a82 fi

For other tools

  • MCP (shep mcp): get_agent_activity, wait_for_agent_activity (60 seconds by default, at most 10 minutes per call), plus decide_feature_gate and answer_agent_question to act on what you see. See MCP server.
  • A2A: each feature is an A2A task whose state follows its activity. See A2A.
  • HTTP: the web daemon serves GET /api/agent-activity and GET /api/agent-activity/wait, which the web UI uses.
  • Herdr: when shep tui runs in a Herdr  pane, it reports blocked (with “needs you: N”), working or idle to Herdr. See Terminal console.

See also