conversation
Conversation commands operate a persistent dialogue between you and one agent on the Host. A turn is one cycle of “you send a message → the agent finishes answering”. At most one turn is in flight per conversation. The agent and workspace must already exist, and the agent must be enabled and authenticated. Start with npx dimo agent list and npx dimo workspace list to obtain IDs.
A running Host and DIMO_TOKEN are required. See Connect to a Host.
npx dimo conversation create
Create a conversation and optionally send the first message immediately.
npx dimo conversation create \
--workspace WORKSPACE_ID \
--agent AGENT_ID \
[--title TITLE] \
[--prompt TEXT]--workspace is the workspace ID (project root or a Git worktree), required. --agent is the agent’s stable kind, for example claude_code or codex, required. --title is the display name; omit it and the Host may name the conversation from the first message. --prompt is submitted as the first user message and starts the first turn.
The response is the new conversation JSON, including id. Later npx dimo conversation send, npx dimo conversation wait, and npx dimo conversation show take that ID as --conversation.
If the agent is disabled or unauthenticated, the Host rejects create. Enable and sign in under desktop Settings → Agents, then confirm with npx dimo agent list.
npx dimo conversation send
Send text to an existing conversation. An idle conversation starts a new turn. If a turn is already running, the text enters the input queue and runs in order after the current turn ends.
npx dimo conversation send \
--conversation CONV_ID \
--workspace WORKSPACE_ID \
--agent AGENT_ID \
--text TEXTAll four flags are required. --text is plain text. This command sends text only: no images, attachments, or plugin actions. --workspace and --agent must match the conversation’s original binding.
The response is the submit JSON. Read turn status afterward with npx dimo conversation show or npx dimo conversation wait.
npx dimo conversation steer
Append guidance to the in-flight turn. It belongs to that turn; no new turn is created.
npx dimo conversation steer \
--conversation CONV_ID \
--turn TURN_ID \
--text TEXT--turn must be the in-flight turn ID, from the turn field of npx dimo conversation show. All three flags are required. If the agent has no steering capability, the Host returns an error; the text stays a steering request and queued input is unchanged.
With no in-flight turn, the Host returns an error. To add work to an idle conversation, use npx dimo conversation send.
npx dimo conversation child / npx dimo conversation fork
Create a child conversation of an existing one, usually for delegation: the parent agent hands part of the work to another agent. npx dimo conversation fork matches npx dimo conversation child.
npx dimo conversation child \
--parent CONV_ID \
--agent AGENT_ID \
[--title TITLE] \
[--prompt TEXT] \
[--hidden]--parent is the parent conversation ID. --agent is the agent for the child. --title and --prompt match npx dimo conversation create. --hidden marks the child invisible (visible=false). Enable Multi-agent collaboration under Settings → Plugins first; otherwise delegation is unavailable.
The response is the child conversation JSON. List relations later with npx dimo conversation relations --conversation CONV_ID.
npx dimo conversation show / npx dimo conversation output
Read the current output projection, including recent messages and turn.status. npx dimo conversation output matches npx dimo conversation show.
npx dimo conversation show --conversation CONV_ID
npx dimo conversation show --conversation CONV_ID --json--conversation is required. --json prints one line so scripts can read turn.status. Terminal statuses are completed, failed, cancelled, and interrupted.
npx dimo conversation relations
List parent-child relations (delegated children). Use the child IDs with npx dimo conversation show or npx dimo conversation cancel.
npx dimo conversation relations --conversation CONV_ID--conversation is required. With no children the response is an empty list.
npx dimo conversation wait
Poll the same read as npx dimo conversation show about once a second until turn.status is completed, failed, cancelled, or interrupted.
npx dimo conversation wait --conversation CONV_ID [--timeout 600]--conversation is required. --timeout is seconds, default 600. Timeout raises Timed out after Ns. The turn may still be running; inspect with npx dimo conversation show, or raise the timeout and wait again.
npx dimo conversation cancel
Cancel the in-flight turn. Timeline content and files already written stay.
npx dimo conversation cancel --conversation CONV_ID [--reason TEXT]--conversation is required. --reason is optional and stored as the cancel reason. To revert files, use Undo on that turn in the desktop session. With no in-flight turn, the Host returns an error.
Example sequence
export DIMO_TOKEN='…'
export DIMO_URL=http://127.0.0.1:17891
npx dimo conversation create \
--workspace "$WS" \
--agent claude_code \
--prompt "List the top-level directory" \
--json
# read id from the output into CONV_ID
npx dimo conversation wait --conversation "$CONV_ID"
npx dimo conversation show --conversation "$CONV_ID"