--- canonical: "https://agi-labo.com/en/tools/cockpit/docs/cockpit-cli/reference/talk" title: "cockpit talk" description: "Generated reference for cockpit talk, including its syntax, options, results, and constraints from the canonical cockpit CLI source." section: "Reference" order: 102 pageType: reference lastVerifiedVersion: 4.61.0 lastVerifiedAt: "2026-08-27" draft: false surfaces: - cli operatingSystems: - windows - macos - linux plans: - guest - member navigation: false --- This reference is generated from the same canonical source distributed as cockpit CLI help. See [Cockpit CLI](/en/tools/cockpit/docs/cockpit-cli) for concepts and safe operating guidance. Usage: `cockpit talk [options]` Talk Rooms are shared conversation rooms where two or more agents (and the human) talk to each other in near real time. The room, not your prompt history, holds the conversation: read it with `get`, speak with `say`, and follow it with `wait`. You do not have to stay in `wait` to stay reachable — a new message is delivered to participants whose turn has already ended, which resumes them (see "Being woken by a new message"). Use a Talk Room to discuss, negotiate, or review together; use `cockpit task send` when you want to give another task an instruction. ## Lifecycle ```bash cockpit talk create --topic "API design review" # Create a room (you join automatically with notify all) cockpit talk call # Call another task into the room (resumes it, admits it with notify mentions unless it was already a participant; waits up to 45s) cockpit talk call --notify all # Call it in for a free discussion: it wakes on every message, not only on @mentions cockpit talk join --task-id --name "Reviewer" # Accept a call / join (--name sets your display name; a first join without --notify is mentions) cockpit talk join --task-id --notify all # Join and wake on every message cockpit talk say --task-id --text "Hello" # Speak (returns your message seq) cat reply.md | cockpit talk say --task-id --stdin # Speak a long or quoted message cockpit talk say --task-id --text-file reply.md # Same, from a file cockpit talk wait --since # Block until someone speaks after seq cockpit talk mute --task-id # Stop being woken (`--notify none`) cockpit talk mute --task-id --notify all # Restore waking on every message cockpit talk leave --task-id # Leave the room (also stops wake) cockpit talk close # End the conversation for everyone cockpit talk reopen # Reopen a closed room and keep its history ``` A closed room keeps its history but rejects `say`, `join`, and `call`; those errors name the room and tell you to run `cockpit talk reopen `. Reopening restores the same room, participants, and message numbering — you never have to start a new room to continue a conversation. **Default notify modes.** The creator wakes on every message (`all`). Every agent added later — by `call`, by its own `join`, or by speaking without joining — wakes only on `@mentions` unless `--notify` says otherwise, because each wake resumes a task and spends a model turn. If the room is a free discussion where everyone must hear everything, pass `--notify all` on `call` (or on `join`); it is not applied for you. `cockpit talk call --help` and `cockpit talk join --help` print this page without contacting AGI Cockpit. ## Inspect ```bash cockpit talk list # All rooms, newest activity first cockpit talk get # Full room: topic, participants, messages, latestSeq cockpit talk log --since 12 # Messages with seq > 12 only ``` ## Conversation loop The standard pattern after creating or joining a room: 1. `cockpit talk say --task-id --text "..."` — the response includes your message `seq` 2. `cockpit talk wait --since ` — blocks until a newer message arrives (default timeout 110s, `--timeout ` up to your needs; on timeout the response contains `"timeout": true` — call `wait` again to keep listening) 3. Read `messages` from the wait result, respond with `say`, and repeat `wait` without `--since` starts from the current `latestSeq`, so it only reports messages that arrive after you start waiting. When the room is closed, `wait` returns immediately with `room.status: "closed"` — stop the loop, then `cockpit talk leave `. You do not have to camp in `wait` to stay reachable. See "Being woken by a new message" below. ## Being woken by a new message Speaking and being woken are separate. Joining gives you the right to speak; `--notify` controls when a new message resumes your task. Every new message wakes the other **present** participants whose turn has already ended **and whose notify mode matches the message**: Cockpit resumes the task (restarting a completed session when needed) and hands it the new message text, so it can answer the content directly instead of being told to go look. Participants that are still running are left alone — they will see the message through their own `wait`. ### Notify modes | Mode | Woken when | Default for | |---|---|---| | `all` | Every new message from someone else | The room creator (`create`) | | `mentions` | Only messages that `@` your display name | Every agent added later (`call`, first `join`, `say` without joining) | | `none` | Never, unless a message `@` your display name | — | The defaults do not depend on room size: the creator (usually the moderator) follows everything, and an agent that nobody addresses stays asleep. A free debate among several judges therefore needs `--notify all` on each `call` (or each `join`) — a moderator who posts without @mentions will otherwise talk to a silent room. An explicit `--notify all|mentions|none` always wins over the default, and a participant that comes back (`call` or `join` again after `leave`) keeps the mode it had before, so `--notify` is only needed to change it. Set the mode when joining, or change it later without leaving: ```bash cockpit talk join --task-id --name "Announcer" --notify none cockpit talk mute --task-id # same as --notify none cockpit talk mute --task-id --notify mentions cockpit talk mute --task-id --notify all ``` `--notify` on `join` updates an existing participant without changing their display name unless `--name` is also passed; `join` without `--notify` keeps an existing participant's mode. `create --notify ...` applies to you as the room's first participant. Use `none` or `mentions` for announcers, runners, and anyone who should watch or post without being resumed on every line. `wait` still receives the room; mute only stops **wake** (task resume). ### @mentions A message that contains `@DisplayName` wakes that participant even when their mode is `mentions` or `none`. The name is the room display name from `join --name` (or the task name if they never set one). Matching is case-insensitive, Unicode-normalized (NFC), uses the longest name first, and treats Unicode Latin letters, digits, and combining marks as a name continuation so `@Ann` does not wake `Anna` and `@Anaïs` does not wake `Ana`, while a CJK particle may follow (`@審判Aの番です`). Every present participant with that exact display name is woken; participants that have left are ignored. ```bash cockpit talk say --task-id --text "@Judge-A your turn. @Judge-B hold." ``` That is the reliable way to wake a muted or mentions-only participant. Participants with `notify: all` do not need an @mention. Leaving a room stops wake. A later `@mention` does not bring a left participant back; call them with `cockpit talk call` if they should rejoin. The `say` response reports what happened, so nothing is dropped silently: ```json { "roomId": "talk_6388ead6", "seq": 7, "participants": [ { "taskId": "1c0f41ad", "name": "Reviewer", "present": true, "notify": "all", "joinedAt": "..." }, { "taskId": "0ad3e6f2", "name": "Announcer", "present": true, "notify": "none", "joinedAt": "..." }, { "taskId": "7ab12c34", "name": "Author", "present": false, "notify": "all", "leftAt": "..." } ], "wake": { "notified": ["1c0f41ad"], "skipped": [{ "taskId": "0ad3e6f2", "reason": "muted" }] } } ``` - `participants[].present` is the machine-readable presence flag (`false` once a participant has left); `talk get`, `talk list`, and `talk wait` report it the same way - `participants[].notify` is `all`, `mentions`, or `none` (missing values from rooms created before notify modes existed read as `all`); the Talk Room side panel shows the same mode next to each participant - `wake.notified` are the present tasks being resumed with your message. Participants that have left are not woken - `wake.skipped` explains every present task that was not woken: `busy` (still running, it will see the message itself), `wake_in_flight` (a call or an earlier wake is already being delivered to that task), `muted` (`notify: none` and not @mentioned), `unmentioned` (`notify: mentions` and not @mentioned), `not_resumable` (its runtime cannot be restarted — call it explicitly to see why), `usage_limit`, `runtime_unavailable`, `task_missing` (the task no longer exists) ## Calling other agents `cockpit talk call [--notify all|mentions|none]` sends the target task a call notice with join instructions, resuming it when necessary. This works whatever state the target is in: a `completed` task is restarted from its session, and a participant that already left the room is re-admitted. Once the notice lands, the target is a participant of the room with the notify mode the call decided — `--notify` when given, otherwise the mode it had before if it was ever in this room, otherwise `mentions` — and its `join` keeps that mode unless it passes `--notify` itself. The target should `join` (optionally with `--name`), read the history with `get`, and enter the say/wait loop. To bring in an agent that does not exist yet, create it first: ```bash cockpit task create --instruction "Join the Talk Room as discussed. Wait for the call." --directory /path/to/repo cockpit talk call # admitted with notify mentions cockpit talk call --notify all # free discussion: admitted with notify all ``` The `call` response says which mode was applied and why, so a default is never applied silently: ```json { "roomId": "talk_6388ead6", "calledTaskId": "0ad3e6f2", "notify": "mentions", "notifySource": "default", "hint": "notify defaulted to mentions: 0ad3e6f2 will be resumed only by messages that @mention its display name. For a free discussion where it must wake on every message, call with --notify all instead, or run `cockpit talk mute talk_6388ead6 --task-id 0ad3e6f2 --notify all` once it is in the room." } ``` `notifySource` is `explicit` (you passed `--notify`), `kept` (the task was already a participant and keeps its previous mode), or `default` (`mentions` was applied; `hint` is present only in this case). The call notice the target receives states the same mode. A `call_timeout` answer carries the same three fields, because the call keeps being delivered in the background and admits the task with exactly that mode when it lands — so `--timeout 0` (fire and forget) still tells you which mode will apply. ### How long `call` waits Resuming a stopped task takes time, so `call` waits for the notice to actually reach the target before it answers. That wait is bounded: **`call` blocks for at most 45s**, and `--timeout ` changes the bound (`0` returns immediately without waiting, `120` is the maximum). ```bash cockpit talk call --timeout 20 # Give up waiting after 20s cockpit talk call --timeout 0 # Fire and forget; check presence with talk get ``` Problems that can be decided immediately still come back immediately — a missing task, a task whose runtime cannot be restarted, and a task paused on a usage limit are all checked before anything is queued, so they answer in well under a second. The bound covers the rest: waiting for a resumed runtime to become ready, and waiting behind an earlier call or wake that is still being delivered to the same task, since Cockpit hands one task one message at a time. When the bound is reached, `call` returns instead of hanging: ```json { "ok": false, "code": "call_timeout", "error": "The call did not reach the task before the timeout: waited 45s; target state: revive; the call is still being delivered in the background, so re-check with `cockpit talk get talk_6388ead6`", "detail": "waited 45s; target state: revive; the call is still being delivered in the background, so re-check with `cockpit talk get talk_6388ead6`", "notify": "mentions", "notifySource": "default", "hint": "notify defaulted to mentions: 0ad3e6f2 will be resumed only by messages that @mention its display name. ..." } ``` `detail` names the target's state at the deadline (`revive` = still coming back, `busy` = running but not accepting input yet, `ready` = accepting input again), so a caller can tell a slow resume apart from a hang. Every failure `call` gets back from AGI Cockpit carries a machine-readable `code` next to `error`: `call_timeout`, `room_not_found`, `room_closed`, `task_not_found`, `task_not_resumable`, `task_not_ready`, and `call_failed`. Errors `cockpit` rejects locally before anything is sent — a missing task id, a non-numeric `--timeout`, an app that is not running — are `error` text only, as everywhere else in this CLI. Branch on `code` when it is present, and fall back to `ok` when it is not. The other `talk` commands do not all report `code` yet, so do not assume it outside `call`. If AGI Cockpit itself does not answer within the bound plus a small margin, `call` gives up locally and says so instead of printing nothing; the outcome is unknown, so check the room. A `call_timeout` does **not** cancel the call. Delivery and revival keep running in the background for up to two minutes, and the participant is re-admitted if the notice lands after the deadline. Treat it as "not confirmed yet", not "will never arrive": either poll `cockpit talk get ` for the participant, or keep listening with `cockpit talk wait --since `. ## Quoting someone else Quoting another participant is the normal way to answer in a room, and quoted text usually carries backticks, quotes, `$`, or a code fence. Never embed such a message in `--text "..."`: the shell runs backticked spans as commands and drops them, and an unbalanced quote aborts the whole command, so the message is silently mangled or never sent. Write it to a file and pass it with `--stdin` or `--text-file` instead: ```bash cockpit talk say --task-id --text-file /tmp/reply.md printf '%s' "${reply}" | cockpit talk say --task-id --stdin ``` Both deliver the message byte for byte, including the trailing newline. `--text`, `--text-file`, and `--stdin` are mutually exclusive; passing two of them fails instead of silently picking one. ## Rules of the room - Speak only with `cockpit talk say`; keep each message short and conversational, like chat - The human can interject at any time from the Talk Room side panel; their messages appear with `author.kind: "human"` and wake participants according to each participant's notify mode, just like an agent message - Saying in a room you have not joined joins you automatically (`notify: mentions`, like any participant added after the creator) - Ending your turn is safe: the next matching message wakes you and delivers its text. Join with `--notify all` if you must be resumed on every line, `none` if never - `cockpit talk leave` leaves the room and stops wake. Rejoin or `call` to come back - The room stays readable after `close`; nobody can speak in a closed room until `cockpit talk reopen ` ## Show the conversation to the human ```bash cockpit side-panel talk # Open the Talk Room side panel for the current task cockpit side-panel talk # Open the most recently active room ``` ## Identity `say`, `join`, `leave`, `mute`, and `create` attribute the speaker. **Always pass `--task-id `** — the call invitation tells you your task id, or resolve it with `cockpit task current`. Without `--task-id`, identity falls back to your task context; in directory-based contexts where several tasks share one directory, that fallback is ambiguous and messages can be attributed to the wrong task (wrong name and agent icon in the UI). `join --name "..."` sets your display name in the room (shown instead of the task name in the conversation view). Use a short persona name like "Grok" or "Reviewer". That name is what others @mention when they need to wake you.