Upgrading

Upgrading

From 1.3 to 1.4

How to update

Use any 1.4 installer: the Mac .pkg, the Windows Setup .exe, or 1. Install from the 1.4 zip. See Installing. Then:

1. Restart After Effects.
2. Restart your AI apps.

Or update from your current panel: its update installs 1.4 too.

What carries over

Everything, automatically: your settings, access token, checkpoints, project history and the AI apps you connected. A ChatGPT connector URL keeps working. Nothing is deleted. The update has been tested from 1.3.4, and as a fresh install, on macOS and Windows 11 with After Effects 2025 and 2026.

If a file is in use while it's being moved (for example on Windows, a running node.exe), everything keeps working where it was and the move is tried again later; installing or updating tries right away. The reason is in ~/.surehand/migration.log. If the move is interrupted (the computer shuts down), the next start finishes it.

Until After Effects restarts

An After Effects that was open during the update keeps running the previous panel. Your AI app keeps working with it. If the previous panel turns a call down, the AI is told "After Effects is still running the previous Surehand panel (v1.3.4). Restart After Effects to finish the update." That is all it takes: no need to re-run the installer.

Backups of AI app settings

Before any AI app's settings file is changed, a backup is made next to it: the very first original as <file>.surehand.bak, plus a timestamped <file>.surehand-<time>.bak for every change, the newest three kept. A settings file that can't be read is left alone and reported, never overwritten.

Claude Desktop extension (.mcpb)

The 1.4 .mcpb installs as a new extension in Claude Desktop, named Surehand MCP. After installing it, remove the previous version's extension in Claude Desktop › Settings › Extensions.

New in 1.4

Pause AI, the approval pop-up, the ☰ screens (Chat, Connect, Checkpoints, Activity history, Updates, Settings) and Undo in the panel's feed; proven edits, precomp surgery, project history, X-ray, Preflight, the stress test, versions, localization and reformat, render profile, handoff and farms, chat in After Effects, in-chat views, the skills, VS Code, Windsurf / Devin Desktop and LM Studio support, and the signed .pkg and Setup .exe installers.

What moves where, for developers: Moving from 1.3.

Updating within 1.4

• In the panel: the footer shows · update ready when a newer release is out. Click the version (or ☰ › Check for updates…), then Update now.
• From a terminal: node ~/.surehand/ae/server/surehand-ae.mjs update. update --check only reports.
• Claude Desktop extension: install the new Surehand-MCP.mcpb from the release page.
• Or run the newer installer over the old one.

Then restart After Effects and your AI apps. Until After Effects restarts, the panel shows Restart After Effects to finish the update, and an AI call that reaches the previous panel says the same. Restarting is all it takes.

What the updater does:

1. Downloads the server from the latest GitHub release of ConformLabs/surehand-mcp.
2. Checks it against the SHA-256 checksum published with the release.
3. Starts it and checks it reports the expected version.
4. Replaces the installed server, keeping the old one as surehand-ae.mjs.previous.
5. Updates the After Effects extension.

If any check fails, nothing is replaced.

The check for new versions asks GitHub at most once a day. Turn it off with "updateCheck": false in config.json or SUREHAND_AE_NO_UPDATE_CHECK=1.

Beta updates

Pre-releases are offered only when you ask for them: ☰ › Settings › Beta updates › On in the panel, surehand-ae update --channel beta, or "updateChannel": "beta" in config.json. You are then offered the newest of the betas and the stable releases, checked and installed the same way. Turning it off (--channel stable) never goes back to an older version: a newer beta stays until a newer stable release is out.

The server also checks the After Effects extension every time it starts, and installs or updates it if needed. After Effects only loads a new extension when it starts, hence the restart.