Agent sessions

Use modular agent to work with the same sessions that appear in Modular. The commands speak the Agent Host Protocol (AHP), not terminal or chat-screen output.

Interactive use

Open the terminal chat client:

modular agent chat

With no arguments, mchat reconnects to the last chat or opens a session picker. Start or reopen a specific session:

modular agent chat --new --model gpt-5.6-luna --cwd /home/me/project
modular agent chat --session tvx:/8b8b0ec8-2e98-4e5b-90f9-f33846c90f55

mchat supports @file references, Modular #tool references, queued messages, tool confirmation, model selection, permissions, sandbox mode, and reasoning visibility. Run modular agent chat --help for keys and slash commands.

Script a session

The reliable order is:

discover host
  └──▶ create and activate session
        └──▶ start log subscriber
              └──▶ send turn
                    └──▶ consume terminal action

1. Find the local host

modular agent hosts --json
modular agent ps --json

hosts lists running local hosts. ps lists active sessions on the discovered host; add --all to include idle and archived sessions.

2. Create and activate a session

modular agent create \
  --cwd file:///home/me/project \
  --activate \
  --json

{
  "session": "tvx:/8b8b0ec8-2e98-4e5b-90f9-f33846c90f55",
  "active": true
}

The active-session marker lets send, logs, stop, and confirm omit the session URI:

modular agent use --show
modular agent use --clear

Model selection is not supported by agent create in the current AHP client. Use agent chat --new --model <id> when the new session needs a specific model.

3. Subscribe before sending

Start the subscriber first so a fast turn cannot finish before observation:

modular agent logs --jsonl \
  --until chat/turnComplete \
  --until chat/turnCancelled \
  --until chat/error

The first line is the current session snapshot. Later lines contain typed AHP actions with their server sequence numbers. There is no implicit completion deadline; --timeout-ms adds one only when the caller wants it.

4. Send the turn

In another process:

modular agent send 'Reply with exactly hi and nothing else.' --json

send returns the turn id after dispatch. The log stream owns progress and completion.

{"turnId":"0fda091d-bc4e-46ac-9aeb-28bbac859043"}

Confirm or stop work

Approve a pending tool call with the turn and tool-call ids from the stream:

modular agent confirm tool-call-id --turn turn-id --json

Deny it with --deny. Use --selected-option-id <id> when the confirmation offers named choices.

Cancel active turns:

modular agent stop
modular agent stop tvx:/8b8b0ec8-2e98-4e5b-90f9-f33846c90f55

Command reference

Command	Use it for
hosts [--json]	discover local agent hosts
ps [--all] [--json]	list sessions
create [--cwd] [--provider] [--activate]	create a session
use <uri>, use --show, use --clear	manage the CLI default session
send [--session] <prompt>	dispatch a turn and return its id
logs [session] [--jsonl] [--until]	read the snapshot and stream actions
confirm <tool-call-id> --turn <id>	answer a tool confirmation
stop [session]	cancel active turns
chat	open mchat
host	start a standalone local agent host
kill	forcefully stop the discovered host process tree

The desktop app normally owns the host. Use host only for a standalone local server and kill only when normal shutdown is unavailable.