Agent API reference

Everything the editor can do, an agent can do through ArcLight's API: about 130 operations behind 13 MCP tools. This page is for people building their own agents or scripts. To connect Claude Code, start with Set up AI agents.

How agents connect

• Off by default. ArcLight listens only while Settings ▸ Agents ▸ Allow agents to control ArcLight is on and the app is open. Regenerate there issues a new token and disconnects everyone using the old one.
• A local Unix socket, never the network. It speaks JSON-RPC 2.0, one message per line. The socket file is readable only by you.
• A token. ArcLight writes the socket path and token to ~/Library/Application Support/ArcLight/agent.json (mode 0600). The first message on a connection must be hello with that token.
• The arclight helper at ArcLight.app/Contents/Helpers/arclight does all of this for you. arclight mcp is an MCP server on stdio that forwards tool calls to the socket.

If you talk to the socket directly, open with:

{"jsonrpc":"2.0","id":1,"method":"hello","params":{"token":"<token from agent.json>","name":"My agent"}}

The name is what the host sees in the activity list. After that, every method on this page is a JSON-RPC method with the same name.

The 13 MCP tools

Every tool takes an optional document (an id or a name). Leave it out to use the frontmost document. For edit and show, the operation's parameters go in args:

edit {op: "add_text", args: {slide: "Intro", name: "Title", string: "Hello", frame: "lower-third"}}
show {op: "take", args: {slide: "#3"}}

Both tools accept any operation name; the split only keeps the tool list readable.

Main edit operations

Main show operations

For the arguments of any operation, call describe {topic: "methods", name: "set_build"}.

Paths and selectors

get, set and patch address any part of the document by path:

get {path: ""}                                        // outline
get {path: "slides[\"Intro\"]"}
get {path: "slides[#2].layers[\"Title\"].kind.text"}
set {path: "slides[\"Intro\"].layers[\"Title\"].kind.text.fontSize", value: 96}
get {path: "script"}
get {path: "output"}

For the outline, depth sets the detail: 0 is slide names only, 1 adds layers (the default), 2 is the full document.

Operations that take several layers also accept "all". Names that don't match come back as an error with the closest matches.

Frames, layouts and colors

• Coordinates are canvas points with the origin at the top left. The default canvas is 1920×1080.
• Frames are {x, y, width, height}, or a named layout: full, center, title-safe, left-half, right-half, top-half, bottom-half, left-two-thirds, right-third, lower-third, pip-top-left, pip-top-right, pip-bottom-left, pip-bottom-right. Picture-in-picture is 28% of the canvas width, 4% from the corner. describe {topic: "layouts"} lists them.
• Colors read back as sRGB {r, g, b, a} from 0 to 1. Writes also accept "#RRGGBB" or "#RRGGBBAA".
• Layer kinds read as one key: kind: {text: {…}}, kind: {camera: {…}}, and so on.

How changes are applied

• One call, one undo step. Every change is a batch, named "Agent: …" in the host's Undo menu and recorded in activity.
• The editor's rules apply. After a path edit ArcLight repairs what the editor wouldn't allow (build order, groups, value ranges) and lists each fix in repairs. Pass strict: true to fail instead.
• Revisions. Each change returns the new revision. Pass ifRevision to set or patch to fail if the document changed since you read it.
• Reasons. Pass reason to set or patch and the host sees it in the activity list.
• Revert. revert {id} undoes one agent change, and refuses with a conflict when the host has edited the same slides since.
• Errors say how to fix them. They carry the path, the expected type, allowed values and a suggestion.

Seeing the show

Three calls return PNG images. Over MCP they arrive as image content, alongside a JSON text part.

• render {slide, width, builds, steps, at} draws any slide. builds: 0 shows it as it first appears; the default is every build run. steps maps graphic layer names to steps. Cameras and screens that aren't already running appear as labeled cards, so a render never turns on a camera.
• grab_program {width} returns the live program frame while the show is playing.
• show {op: "get_scopes", args: {camera, kind}} returns a camera's waveform, parade, vectorscope or histogram.

Events

wait_events returns events after a cursor as soon as there are any, or an empty list after timeout seconds (default 25, at most 60). Pass the returned cursor as since next time. Leave since out to start from now. Filter with types, using exact names or prefixes like "live.*".

wait_events {since: 118, types: ["live.*", "cue.fired"], timeout: 30}

describe topics

overview, ops, methods, schema, effects, filters, transitions, builds, generators, titlePresets, textStyles, templates, fonts, looks, sources, blendModes, masks, shapeForms, layouts, events and graphics (the web graphic contract and its JavaScript API). Add name for one entry, such as describe {topic: "effects", name: "gaussianBlur"}.

Scripts: arclight call

The helper also makes single calls from Terminal or a shell script. It prints the result as JSON, and exits 1 with the error on stderr if the call fails.

A="/Applications/ArcLight.app/Contents/Helpers/arclight"
"$A" status
"$A" call list_documents
"$A" call take '{"slide": "#2"}'
"$A" call render '{"slide": "Intro", "width": 640}'

With call, use the method name directly (take, not show). The JSON goes in one argument, so quote it.