An agent in the desktop window

An agent working beside you in a terminal can also work in the Orbitron window you have open: open the file you mean, select the atoms it is talking about, turn the camera to them, draw the orbital it just gave you a number for, and take a picture of the view to check what it drew. You watch it happen and can take over at any point.

It does this through orbitron mcp --attach, a Model Context Protocol server the agent starts. The server talks to the window over a private local socket; nothing leaves your machine. Numbers still come from the orbitron command line, which the skill teaches agents to use. The window is for showing.

Turn it on

In the desktop, open Preferences and, under AI agents, tick Allow an AI agent to work in this window. It is off by default, and turning it off disconnects any agent at once.

Then register the server with your agent, once:

# Claude Code
claude mcp add --scope user orbitron -- orbitron mcp --attach

# Codex
codex mcp add orbitron -- orbitron mcp --attach

Codex stops a tool call after 60 seconds unless told otherwise, which is shorter than you may take to allow the connection or a large file takes to open. Add to ~/.codex/config.toml:

[mcp_servers.orbitron]
tool_timeout_sec = 600

For OpenCode, add the server to opencode.json:

{
  "mcp": {
    "orbitron": { "type": "local", "command": ["orbitron", "mcp", "--attach"] }
  }
}

To check the window answers without an agent:

orbitron mcp --attach --ping

It asks you to allow the connection in the window, then prints what the window has open.

What the agent can do

Tool	What it does
`status`	Reads what is open: file, atoms, formula, frames, selection, style, surfaces, camera
`open_file`	Opens a file, as File > Open does, and waits until it has loaded; an XTC trajectory with the topology the agent names
`select`	Selects atoms by a selection expression
`selection`	Reads what is selected, including what you selected by hand
`camera`	Frames everything or the selection, a preset view, down a lattice axis, from one set of atoms toward another, or a given angle
`style`	Ball and stick, space fill, sticks or element labels
`boundary`	Draws more of a crystal than one cell, as Appearance > Crystal’s Boundary does; the structure is not changed
`measure`	A distance, angle or dihedral
`show_orbital`	Draws an orbital (`homo`, `lumo+2`, a vector number) in Analysis > Surfaces
`hide_surfaces`	Stops drawing surfaces
`screenshot`	A picture of the view as you see it, also saved to a new file when asked
`edit_mode`	Turns Edit mode on, or off when there is nothing for you to review
`edit`	In Edit mode, on the selection: change an element, delete atoms, adjust hydrogens, set or remove a bond, Clean or Relax the geometry, undo, redo
`save_as`	Writes the structure, edits included, to a new `.xyz`, `.pdb`, `.gro`, `.mol` or `.sdf` file

Each edit is the Edit menu’s own command, so it goes on the same undo stack as yours and Edit > Undo takes it back. The agent writes only files that do not exist yet: a screenshot it was asked to save, or a structure through save_as.

What you see

The first time an agent calls a tool, the window asks An AI agent wants to connect, naming the agent. Nothing happens until you choose Allow; Deny turns it away. One agent at a time can be connected to a window.

While one is connected, a badge in the corner says so, with three buttons:

Pause makes the window refuse every request until you resume. The agent is told it was paused.
Disconnect drops the agent. If it calls again, you are asked again.
Activity lists each request the agent made and how it went.

Everything the agent changes is visible and can be changed back by hand: the selection, the camera, the style, which surfaces are drawn, the file that is open, and each edit, with Undo. The status line marks the agent’s edits (“Agent: Deleted 3 atom(s)”), and the Activity list has every request.

What it will not do for an agent

Anything that would put a question to you in the window is refused, with the reason passed to the agent, rather than asked behind your back:

opening a file while the window is in Edit mode, where your edits are;
opening a file over the size limit set in Preferences, or one the memory check would warn you about;
opening an XTC trajectory unless the agent names its topology, whose coordinates must then match the first frame (pairing a topology from another frame is yours to decide);
drawing orbitals, or relaxing a structure, when the memory check would warn you;
leaving Edit mode with edits you have not reviewed: keeping or discarding them is your choice, in the window.

Who can connect

Only processes run by you, on this machine. On macOS and Linux the window listens on a local socket in a directory only your account can enter, and refuses a connection from another user’s process; on Windows it listens on a named pipe whose access list admits only its owner. Each window has a fresh random token, which a client must present; it is written to a file only you can read and removed when the window closes. Text the file contains, such as residue names or titles, reaches the agent as data.

Limits

Edits that need a pointer stay yours. Placing an atom or a fragment by clicking where it goes, and dragging atoms, have no tool.
An edited calculation loses its orbitals while editing. Edit mode on a calculation’s output works on a copy of the structure, as it does for you; show_orbital has nothing to draw until Edit mode is off again.
One window per agent. With several windows allowing an agent, orbitron mcp --attach --session <pid> picks one; orbitron mcp --attach --ping lists their process ids when it cannot choose.