Working with an agent in the Terminal

An agent CLI in the Terminal is a session like any other — with one important difference: the agent’s interface takes a while to take over the panel. Almost every “my text arrived wrong” problem comes from there.

Create the session with the agent already in it

Prefer creating the session with the agent instead of opening a shell and typing the command: that way the session is born with the right process, without a window in which a shell is in control.

At the moment creation finishes, the agent is still starting up. What that implies:

• Writing now makes the text land in the shell, and the agent’s interface takes over afterwards — the message arrives scrambled.
• The panel may look ready before it is.
• Sessions created from a Canvas card may take a few seconds to show up in the list.

Safe sequence for sending the first message

1. Create the session with the agent.
2. Wait for the agent’s interface to go idle.
3. Read what is on screen — that is what confirms the interface took over.
4. Send the text and ask for Enter.
5. Wait again before reading the result.
6. Read only what is new, from the previous read’s cursor.

The reading, sending and waiting contract is in Reading, sending and waiting.

Swap the agent without closing the session

When the agent needs to change — switching provider, resuming a task with another model — there is an operation that replaces the process while keeping the session:

• The session identifier stays valid.
• The Canvas card, its position, its edges and the title survive.
• The previous agent’s in-memory state is not preserved.
• Automations that reused exactly that session fall back to a new session.

Forking a session and copying context — a limited feature

The panel’s context menu offers two gestures for agent sessions:

• Fork the agent session — asks for a fork of the current session, to continue the work on another branch without abandoning what exists.
• Copy context — copies the context associated with the panel.

Limited feature. The availability and the effect of both gestures depend on the agent session type: the menu always shows the items, but what they deliver varies with the session.

Copying context may include sensitive data. The content copied is the session’s context; before pasting it elsewhere, know what is going along.

What belongs to other screens

• The switch between native chat and terminal is the Chat screen’s subject, not this page’s: the Terminal screen shows terminal.
• The blocked-input notice on a remote workspace belongs to the remote environments surface.
• The phone remote-control overlay belongs to the devices surface.

Related

• Creating and navigating between sessions
• Terminal command reference