Skip to content

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):

HookMatcherRuns
Notificationpermission_prompt|elicitation_dialogclusto internal notify-state --waiting
PreToolUseAskUserQuestionclusto internal notify-state --waiting --reason question
PostToolUseAskUserQuestionclusto internal notify-state --idle
Stop-clusto internal notify-state --idle
UserPromptSubmit-clusto internal notify-state --idle
StopFailureserver_error|overloadedclusto internal notify-state --failed
  • Clusto recognises its entries by their internal notify-state command. Your own hooks are never changed or removed.
  • The command is the absolute path of the clusto CLI installed next to clustod, so it works even when clusto is not on the agent's PATH. Outside a Clusto session the command exits silently.
  • The idle_prompt notification 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.asked and question.asked as waiting, with the permission or question text as the prompt;
  • reports permission.replied, question.replied, question.rejected and session.idle as idle;
  • registers the clusto MCP server through opencode's config hook, so opencode.jsonc is never rewritten. A clusto MCP 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:

HookMatcherRuns
NotificationToolPermissionclusto internal notify-state --waiting --reason permission
BeforeToolask_userclusto internal notify-state --waiting --reason question
AfterToolask_userclusto 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):

HookMatcherRuns
notificationpermission_promptclusto internal notify-state --waiting --reason permission
notificationelicitation_dialogclusto internal notify-state --waiting --reason question
postToolUseask_userclusto 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 arriving
  • Server error mid-response
  • Connection lost before a response was produced
  • Your computer went to sleep mid-response
  • an overloaded API (the StopFailure hook above, which runs clusto 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 for auto-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 ​

  1. 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.

  2. The tool reports its state by running the clusto CLI:

    When the agent starts waiting for the user:

    bash
    clusto internal notify-state --waiting --reason question --prompt "<the question>"
    • --reason is free text, e.g. question, permission, or input.
    • --prompt is 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:

    bash
    clusto internal notify-state --idle
  3. Wire it to hooks. Any tool with a "blocked / waiting" event and a "turn finished" event can call --waiting on the first and --idle on the second. Hook payloads arrive as JSON on stdin, and clusto internal notify-state also reads the message / transcript_path fields from that JSON when --prompt is 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 clusto CLI 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_ID is 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.

Clusto - remote AI coding agents over WebSocket.