The Surehand panel

The Surehand panel

Open it with Window › Extensions › Surehand MCP. Dock it anywhere, like any After Effects panel.

The panel is where you see what the AI does and decide what it may do. You don't need it open for the AI to work: the bridge that connects After Effects to the AI starts by itself with After Effects.

What's in the panel

Part	What it shows
Status (top)	The connection, with a green, amber or grey tile. See Status.
Pause (top right)	Pause AI. Turns into Resume while paused. See Pause AI.
Chat (speech bubble, top right)	Chat with Codex, Claude Code or Antigravity inside After Effects. See Chat in After Effects.
☰ (top right)	The panel's menu: chat, connect apps, checkpoints, history, settings and help. See The ☰ menu.
Restart notice	"Restart After Effects to finish the update." Shown after an update while After Effects still runs the previous panel. See Updates.
What the AI may do	The mode: Full, Ask or Read-only, with one line saying what it means.
Approval card	Only in Ask mode, while a change waits for you. See Approvals.
Feed	The latest things the AI did, newest first, and background renders in progress. All activity › below it opens the full history.
Footer	Your After Effects version, and the Surehand version. Click the version for Updates. It reads · update ready when a newer release is out.

Status

Status	Meaning
Ready · <app> (green)	Connected. The name is the AI app that called most recently.
No AI app connected (grey)	No AI app has used Surehand yet. The panel offers to set one up.
Waiting for you (green)	In Ask mode, a change waits for Allow or Deny. With more than one: · n requests.
AI paused (amber)	You paused the AI.
Connecting to After Effects… (grey)	The panel just opened and the bridge is still starting (a few seconds).
Not connected to After Effects, Bridge problem: …, Token mismatch: re-run the installer, Settings file can't be read: … (grey)	Something is wrong. The panel shows a Test the connection button, and Troubleshooting has more.

While After Effects runs a long script, the whole panel (like the rest of After Effects) waits until it is done. That is normal: the panel doesn't report a problem for it. If After Effects keeps a call waiting because it is busy or shows a dialog, a row above the feed says so.

When no AI app is connected yet, the panel shows a line such as "Claude Desktop isn't set up yet." with a Set it up button. After setting up, restart that app.

Modes

What the AI may do has three choices. A change applies to the AI's next request; no restart is needed.

Mode	What happens
Full (default)	The AI edits your project directly. Every step it takes can be undone. Your AI app may still ask you before each tool call; that is the app's own setting.
Ask	Every change and every script waits for your Allow or Deny in After Effects. Reading the project is never held. See Approvals.
Read-only	The AI can look at the project and preview frames, but can't change anything. Editing tools are refused. Scripts still run to read information; if one changes the project, the change is undone at once and the AI is told what it tried. See What the AI can do.

The mode is stored as "permissions": {"mode": "full" | "ask" | "read-only"} in ~/.surehand/ae/config.json. If that file can't be read, Surehand fails closed: it behaves as Read-only, with no shell commands, until the file is fixed.

Keyboard: the mode buttons are a radio group; the arrow keys move between them.

Pause AI

Click the pause button at the top right of the panel.

• While paused, nothing runs in After Effects. Every call from the AI, reads included, is refused at once with "Paused in the Surehand panel: nothing was run. Ask the user to resume." The AI stops instead of waiting.
• The panel shows how many calls were refused so far.
• A call that was waiting in the queue and hadn't started yet is refused too. A script that is already running inside After Effects is not cut short (After Effects can't interrupt a running script).
• The panel's own actions (Undo, checkpoints, the connection test) still work while paused.
• Click Resume to let the AI work again.

The pause is held by the bridge inside After Effects and saved in config.json, so it survives a restart of After Effects. Only the panel can pause or resume: the AI app can't, even though it can read and edit config.json. See Security.

Pause protects against the AI app. A program with full shell access as your user account is out of scope; see Security.

The feed

The feed lists what the AI did, newest first: 7 items in the default layout, 6 when narrow, 5 when wide.

Icon	Kind
Green diamond	A change to the project
Check mark	A proof that passed (Proven identical, Preflight passed)
Red mark	A problem: a failed call, Not identical, Preflight: n problems, Preflight incomplete
Amber circle	Not run: you stopped it (Pause, Deny, Read-only mode, shell commands off) or no one answered within 10 minutes. Not a failure.
Eye (grey)	The AI only looked
Progress bar	A background render in progress, with percent (and time left in the wide layout)

Click any row for what happened: the change list, or the script and its result. Several looks in a row are one row (Looked at the project). The full history is under ☰ › Activity history.

Undo in the feed

The newest change can show Undo. It runs Edit › Undo in After Effects. Because Edit › Undo undoes whatever happened last, Surehand only offers it when it is certain that this is the AI's own last step:

• it is the newest entry in the log, and it changed the project;
• the call made exactly one undo step;
• it ran in this After Effects (same bridge and process) and in the project that is open now;
• nothing has changed the project since (After Effects' project revision is the same). This is checked again inside After Effects right before undoing.

If any of these isn't true, there is no Undo button, or you get "The project changed since then: use Edit › Undo in After Effects." After undoing, Edit › Redo brings the change back.

Layouts

The panel adapts to how you dock it:

Layout	When	Differences
Narrow	less than 260 px wide	Short labels (Full / Ask / Read, "Ready", "Paused"), shorter mode description, 6 feed items
Default	otherwise	Full labels, 7 feed items
Wide (two columns)	more than 560 px wide and at most 300 px tall	Mode and status on the left, feed on the right; Undo and Show sit at the right of each row; render rows show time left; 5 feed items

The minimum panel size is 240 × 200 px.

The ☰ menu

Click ☰ in the panel's header. The same items are in After Effects' own panel menu (the ☰ next to the panel's tab). Screens opened from the panel's menu go Back to it.

The menu has three groups: Work, Settings and Help.

Item	What it does
Chat with your AI app (Work)	The chat. See Chat in After Effects.
Panel opens on: Activity / Chat (Settings)	What you see first when After Effects starts. Stored as panelOpensOn.
Beta updates: On / Off (Settings)	Also offer pre-releases. See Updates. Stored as updateChannel.
Shell commands in scripts: Allowed / Off	Whether scripts may call system.callSystem. Off refuses such scripts before they run. A safeguard, not a sandbox: scripts can still read and write files. Stored as permissions.allowShell.
Tools the AI sees: Core (faster) / All tools	How many tools are sent to the AI app up front. Restart the AI app to apply. See What the AI can do. Stored as toolProfile.
Connect an AI app…	Set up or remove AI apps, start ChatGPT on the web, copy the settings for other apps. See Connecting AI apps.
Checkpoints…	Safety copies of the open project: Save one now, Compare with now, Open a copy. See Checkpoints.
Activity history…	Every call, grouped by day. Search layers, comps and tools; filter All / Changes / Problems; click an entry for what changed. Open log file shows activity.jsonl. Shows up to 300 entries at a time.
Test the connection	Runs the same checks as 2. Test Installation and shows "n of n checks passed". A failed connection to an AI app has a Fix button. Run again repeats it.
Copy diagnostics	Copies a report for a bug report: versions, paths, settings (the token is replaced by its length), bridge status and the last 15 calls.
Updates	The Updates screen: the new version's release notes, What's new and Update now. Click once a day next to "Check automatically" to turn the daily check off (or on). See Updates.
About & help	Version, links to this wiki and to report a problem.

The ☰ screens slide over the feed. Back (or Esc) returns.

The screens that run the server (Connect an AI app, Connection test, Updates, Save one now, Compare with now) need the server installed with an installer (.pkg, Setup .exe or the zip). With only the Claude Desktop extension (.mcpb) they say so. Copy diagnostics, Activity history and opening a checkpoint work either way.

Updates

• The footer reads · update ready when a newer release is out (checked against GitHub at most once a day). Click the version, or ☰ › Check for updates…, then Update now.
• ☰ › Settings › Beta updates › On also offers pre-releases: the newest of the betas and the stable releases. Turning it off never goes back to an older version: a newer beta stays until a newer stable release is out.
• After an update, After Effects keeps running the previous panel until it restarts. The panel then shows Restart After Effects to finish the update. Until you do, an AI call that reaches the previous panel says "After Effects is still running the previous Surehand panel (v…). Restart After Effects to finish the update." Nothing else needs doing: no installer, no new token.

See Upgrading.

Several After Effects at once

Each running After Effects has its own bridge and its own panel. The panel always shows and controls the bridge of the After Effects it is in. A pause set in one After Effects' panel is saved in config.json, and the other running After Effects pick it up as well and hold it. To resume everywhere, click Resume in the panel of each After Effects that shows AI paused.