Appearance
Agent Waiting-for-Input Marker
When an AI agent running inside a Clusto terminal session blocks on you - a permission prompt, a question, or any input request it can't proceed without - Clusto marks that session and can notify you. This lets you walk away from a long agent run and come back exactly when it actually needs an answer.
There are two parts:
- A waiting marker in the sidebar: an amber question disc on the session row, a
?before its name, and waiting counts on the project folder and the Terminals header, so you can spot a waiting session at a glance. - An optional notification with a Copy button that copies the question / prompt text, so you can paste it elsewhere.
The waiting marker
The marker appears whenever the agent in that session is genuinely asking for an answer - not merely when it has stopped or finished a turn. A finished-but-unanswered turn does not earn it.
The marker is driven by signals the agent reports to the daemon, so every connected device shows the same state. It clears as soon as the agent reports it is no longer waiting. The counts span every online node; Go to next waiting session in the F1 command palette jumps to each waiting session in turn. See Sidebar markers for the other row markers.
Set up automatically
Claude Code, Codex, opencode, Gemini CLI and GitHub Copilot CLI need no manual setup. Every node wires the marker for them as part of its periodic AI setup reconcile, which runs when the daemon starts, after knowledge changes and every 5 minutes. The AI setup page lists one check per tool: Claude Code waiting status, Codex waiting status, opencode waiting status, opencode MCP server, Gemini CLI waiting status and GitHub Copilot CLI waiting status. If one is not green, run Fix now there, or use Node Doctor to fix every node at once.
Claude Code
Clusto adds its own hook entries to the agent user's ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json):
| Hook | Matcher | Runs |
|---|---|---|
Notification | permission_prompt|elicitation_dialog | clusto internal notify-state --waiting |
PreToolUse | AskUserQuestion | clusto internal notify-state --waiting --reason question |
PostToolUse | AskUserQuestion | clusto internal notify-state --idle |
Stop | - | clusto internal notify-state --idle |
UserPromptSubmit | - | clusto internal notify-state --idle |
StopFailure | server_error|overloaded | clusto internal notify-state --failed |
- Clusto recognises its entries by their
internal notify-statecommand. Your own hooks are never changed or removed. - The command is the absolute path of the
clustoCLI installed next toclustod, so it works even whenclustois not on the agent'sPATH. Outside a Clusto session the command exits silently. - The
idle_promptnotification is deliberately not wired, so a finished-but-unanswered turn does not produce a false?. - For
AskUserQuestion, the text behind the Copy button is the question from the hook payload.
Codex
Nothing is written. Codex 0.166 and later report approvals and questions with OSC 7501 on their own. Older Codex releases show an Action Required terminal title while they wait, which Clusto reads instead. Either way the marker clears when Codex continues. Codex chats in the Chats view run without approval prompts, so they never wait.
opencode
Clusto writes a plugin it owns at ~/.config/opencode/plugins/clusto.js. Its first line is // clusto:managed; Clusto rewrites the file, so edits are lost. The plugin:
- reports
permission.askedandquestion.askedas waiting, with the permission or question text as the prompt; - reports
permission.replied,question.replied,question.rejectedandsession.idleas idle; - registers the
clustoMCP server through opencode'sconfighook, soopencode.jsoncis never rewritten. AclustoMCP entry you wrote yourself wins.
A file at that path without the // clusto:managed marker is reported as an error on the AI setup page and left alone. Move it away, then run Fix now.
Gemini CLI
Clusto adds its own hook entries to ~/.gemini/settings.json, the file that already holds the clusto MCP server:
| Hook | Matcher | Runs |
|---|---|---|
Notification | ToolPermission | clusto internal notify-state --waiting --reason permission |
BeforeTool | ask_user | clusto internal notify-state --waiting --reason question |
AfterTool | ask_user | clusto internal notify-state --idle |
BeforeAgent | - | clusto internal notify-state --idle |
AfterAgent | - | clusto internal notify-state --idle |
Clusto recognises its entries by their internal notify-state command. Your own hooks are never changed or removed.
GitHub Copilot CLI
Clusto owns the file ~/.copilot/hooks/clusto.json (version 1):
| Hook | Matcher | Runs |
|---|---|---|
notification | permission_prompt | clusto internal notify-state --waiting --reason permission |
notification | elicitation_dialog | clusto internal notify-state --waiting --reason question |
postToolUse | ask_user | clusto internal notify-state --idle |
userPromptSubmitted | - | clusto internal notify-state --idle |
agentStop | - | clusto internal notify-state --idle |
Clusto rewrites this file, so edits are lost; put your own hooks in another file in ~/.copilot/hooks/. If a file with that name exists and is not Clusto's, the AI setup check shows an error and the file is left alone. Move it away, then run Fix now.
Cursor
Cursor has no hook that fires while it waits for you, so Clusto cannot wire it. Use the copyable instructions under Works with any AI CLI.
Auto-continue after a dropped response
When Claude Code in a Clusto terminal session stops on one of these errors, Clusto types continue and Enter into that terminal for you:
API Error: Connection lost mid-response. The response above may be incomplete.The response stopped arrivingServer error mid-responseConnection lost before a response was producedYour computer went to sleep mid-response- an overloaded API (the
StopFailurehook above, which runsclusto internal notify-state --failed)
How it behaves:
- Clusto waits before typing: 2 seconds for a dropped connection, 30 seconds for a server error or an overloaded API.
- If you type in that terminal during the wait, the automatic continue is cancelled. Plain keys count; focus and mouse reports do not.
- At most 3 automatic continues per session in 10 minutes, so a dead link cannot loop. After that the error stays on screen for you to handle.
- Authentication, billing, usage-limit and context errors are never auto-continued.
- The node that owns the session decides and types, so it works while the app is closed.
- Each scheduled, cancelled or undelivered continue is written to the node log (
clusto logs daemon, search forauto-continue), so you can tell afterwards whether it fired or your typing cancelled it.
The StopFailure hook is written with the other Clusto hooks by the node's AI setup. Chats are separate: a Claude mid-stream cut in a chat is shown as a network error on the chat failure card.
Turning it off
Knowledge > AI setup > Turn off on a node removes the Claude Code and Gemini CLI hooks, the Copilot hooks file and the opencode plugin together with the rest of the node's AI setup.
Attention list
The Attention view (route /attention) is the 7-day notification history: the alerts Clusto raised for agents waiting for an answer, finished turns, task results and new reports, from every node. It has no tabs. Mark all read in the header clears the unread count and also marks read every unread chat, Azure DevOps item, report and terminal bell marker (see Read state). Open it with Mod+Shift+A (Ctrl+Shift+A, or Cmd+Shift+A on macOS), Mod+I (outside text fields and terminals), the bell in the sidebar header (on mobile, the bell in the header), the Attention entry in the Android menu, or Open attention list or Open notification history in the F1 palette; all of them open this same page. The bell shows a count of agents waiting for an answer plus unread notifications.
The Filter button in the header chooses which kinds of alert the list shows and which ones count on the bell and the Attention badge (see Choose what to show and count).
Each unread row has a check button to mark just that alert read, and a group card header has a Mark all in ... read button that names the group (see Read state).
Selecting an entry opens the terminal or chat it came from. If an agent never reports that it waits, run Node Doctor to check that every agent on every node reports.
Copy-prompt notification
When a session starts waiting, Clusto can fire a notification carrying the prompt text the agent set:
- In-app: a toast with a Copy action that copies the question / prompt to your clipboard.
- App backgrounded: a native OS alert is shown instead.
If the agent did not pass an explicit prompt, Clusto falls back to the agent's last message.
On Android, a session that started waiting while the app was fully closed can still reach you: with Background Notifications enabled, the app polls the cluster on a ~15 minute timer and raises a native notification for the waiting state it missed.
Works with any AI CLI
The ? marker is tool-agnostic. Claude Code, Codex, opencode, Gemini CLI and GitHub Copilot CLI are wired for you (see above); any other AI CLI or agent can drive the marker through a small generic contract.
The contract
Every command Clusto runs in a terminal receives the environment variable
CLUSTO_SESSION_ID- the id of the Clusto session the process runs in. You never pass ids around; the CLI reads it from the environment.The tool reports its state by running the
clustoCLI:When the agent starts waiting for the user:
bashclusto internal notify-state --waiting --reason question --prompt "<the question>"--reasonis free text, e.g.question,permission, orinput.--promptis optional and feeds the notification's Copy button. If you omit it, Clusto uses the agent's last message.
When the agent is done / no longer waiting:
bashclusto internal notify-state --idleWire it to hooks. Any tool with a "blocked / waiting" event and a "turn finished" event can call
--waitingon the first and--idleon the second. Hook payloads arrive as JSON on stdin, andclusto internal notify-statealso reads themessage/transcript_pathfields from that JSON when--promptis omitted.
For reference, the Claude Code setup Clusto writes is exactly this contract: --waiting on permission and question events, --idle on Stop and UserPromptSubmit. Do not wire a "finished a turn" idle-prompt event to --waiting, so a finished-but-unanswered turn does not produce a false ?.
Without the CLI: OSC 7501
A tool that cannot run the clusto CLI (for example over SSH to a machine without it) can drive the same marker with terminal escape sequences. Print ESC ] 7501 ; state=blocked:kind=question:msg=<base64> ST to show the ? with a copyable prompt, and state=idle to clear it. See Terminal Notifications, Progress and Bell for the full format and the other states.
Requirements
- The
clustoCLI must be reachable. clustod installs it automatically next to itself on startup if missing - no user action needed. For other tools, put it on PATH or call it by its absolute path. - Run the commands on the same machine as the session;
CLUSTO_SESSION_IDis set for you automatically.
Node Doctor
Settings > Node Doctor (System group) lists every cluster node with its AI setup status, including the waiting-status checks above. See Node Doctor for the details. Use Fix on a node, or Fix all, to rewrite missing hooks and plugins.
A This device row at the top covers the device you are using, so you can see why a waiting agent did not alert you: system notification permission, alert popups, alert sound, Android background checks and muted sessions. Send test notification raises a sample alert through the same path a waiting agent uses.
Settings
The footer of the Settings > Node Doctor card has a Copy setup instructions button. Claude Code, Codex, opencode, Gemini CLI and GitHub Copilot CLI no longer need it: it copies the generic instructions above so you can hand them to other tools, such as Cursor. To check or repair the automatic setup, use Settings > Node Doctor.