Settings and files

Settings and files

Most settings are in the Surehand panel. This page is the reference for everything behind it: the folder layout, config.json, environment variables and logs.

~ is your home folder: /Users/<you> on a Mac, C:\Users\<you> (%USERPROFILE%) on Windows.

Folder layout (1.4)

~/.surehand/                 shared by the Surehand apps
  node/                      private Node.js, if the installer added one
  ffmpeg/                    FFmpeg for Preflight, if you allowed the download (SOURCE.json says what and from where)
  migration.log              the move from 1.3, if there was one
  ae/                        Surehand MCP for After Effects
    config.json              settings and the access token (readable only by you)
    server/surehand-ae.mjs   the server (surehand-ae.mjs.previous: the one before the last update)
    runtime.json             which Node.js and server the panel runs for its ☰ screens
    activity.jsonl           every tool call (see Activity log)
    checkpoints/             safety copies of your projects, one folder per project
    history/                 project history snapshots
    proofs/                  reference frames for proven edits (7 days, 30 at most)
    profiles/                render profiles (7 days, 30 at most)
    stress/                  stress test runs: failing frames and contact sheets (the newest 20 runs)
    copies/                  what each deep duplicate made, for remove_copies
    chat/                    Chat in After Effects: working folder and the last turn's log per agent
    skills/                  the Surehand skills as zips, to upload in Claude Desktop chat
    renders/                 background render logs and status (<id>.log, <id>.json; newest 50)
    instances/               one file per running After Effects bridge
    bridge-status.json       the last bridge status (for diagnostics)
    update-check.json        the last update check
    chatgpt.json             ChatGPT on the web: state and address (readable only by you)
    compat/                  self-test compatibility reports
    tmp/                     temporary files (Preflight thumbnails, previews); cleaned up automatically
    extension-hash           which After Effects extension is installed
    install.log              Mac .pkg install log

The After Effects extension itself is in the CEP extensions folder: ~/Library/Application Support/Adobe/CEP/extensions/com.aemcp (Mac) or %APPDATA%\Adobe\CEP\extensions\com.aemcp (Windows). Don't edit files there: After Effects skips a signed extension whose files changed.

config.json

~/.surehand/ae/config.json. Created by the installer, or by the bridge on After Effects' first start. It is read on every call, so most changes apply without a restart (exceptions are noted).

It's plain JSON. If the file can't be read (a typo, a half-saved edit), Surehand never replaces it: it uses the last good copy it read, and if there is none it refuses changes to the project (it behaves as Read-only) and says why. Fix the file, or re-run the installer, which keeps a good file as it is.

Key	Type	Default	Meaning	Also set in
token	text	random, made at install	Access token for the bridge and the HTTP server. See Security.	—
bridgePort	number	8765	First port the bridge in After Effects tries; it takes the first free one of the next 10. Restart After Effects and the AI app after changing it.	—
httpPort	number	8766	Port of the HTTP server (--http, ChatGPT on the web).	—
permissions.mode	"full", "ask", "read-only"	"full"	What the AI may do.	Panel: What the AI may do
permissions.allowShell	true / false	true	Whether scripts may call system.callSystem.	Panel: ☰ › Shell commands in scripts
toolProfile	"core", "full", or "core,<tool>,<tool>"	"core"	Which tools are sent to the AI app up front. Restart the AI app.	Panel: ☰ › Tools the AI sees
changeReport	true / false	true	The change list after each edit.	—
updateCheck	true / false	true	Check GitHub for a new version, at most once a day.	—
updateChannel	"beta"	— (stable)	Also offer pre-releases.	Panel: ☰ › Settings › Beta updates; surehand-ae update --channel beta
panelOpensOn	"chat"	— (activity)	What the panel shows first when After Effects starts.	Panel: ☰ › Settings › Panel opens on
instance	text	—	Preferred After Effects when several run: "2026", "26.5", or a bridge port.	—
scriptFolders	list of paths	—	Your own script folders, listed by ae_list_scripts. ~ is allowed.	—
blockedAfterSeconds	number	3	Report "After Effects is busy or showing a dialog" when it hasn't accepted a script for this long. 0 waits for the full timeout.	—
startupWaitSeconds	number	15	How long ae_status waits for an After Effects that is still starting.	—
ffmpegPath, ffprobePath	absolute paths	—	FFmpeg / ffprobe for Preflight, instead of searching.	—
paused, pausedAt	—	—	Written by the bridge while the AI is paused. Deleting them does not resume: only the panel's Resume does.	Panel: Pause AI

Example (placeholders):

{
  "token": "<set by the installer>",
  "bridgePort": 8765,
  "httpPort": 8766,
  "permissions": { "mode": "ask", "allowShell": false },
  "toolProfile": "core",
  "scriptFolders": ["~/Documents/AE Scripts"],
  "instance": "2026"
}

Environment variables

For the server (what your AI app starts). An empty value counts as unset.

Variable	Overrides	Meaning
SUREHAND_AE_CONFIG	—	Path of the config file. Instances, logs and the other files are then kept in the folder it is in. The After Effects extension honours it too, if After Effects was started with it.
SUREHAND_AE_BRIDGE_PORT	bridgePort	Port of the bridge to talk to.
SUREHAND_AE_TOKEN	token	Token for the bridge.
SUREHAND_AE_HTTP_PORT	httpPort	Port for --http.
SUREHAND_AE_HTTP_TOKEN	token	Token required by the HTTP server.
SUREHAND_AE_TOOLS	toolProfile	core, full, or core,<tool>,….
SUREHAND_AE_INSTANCE	instance	Preferred After Effects.
SUREHAND_AE_BLOCKED_AFTER_SECONDS	blockedAfterSeconds
SUREHAND_AE_STARTUP_WAIT_SECONDS	startupWaitSeconds
SUREHAND_AE_NO_UPDATE_CHECK	updateCheck	Any value turns the update check off.
SUREHAND_AE_NO_AUTOSETUP	—	Don't install or update the After Effects extension when the server starts.
SUREHAND_AE_NO_ACTIVITY_LOG	—	Don't write the activity log.

Command-line options of the server: --tools core|full, --http [--port <n>] [--host <address>] [--no-auth]. See For developers.

Activity log

Every tool call is recorded in ~/.surehand/ae/activity.jsonl, one JSON object per line: time, AI app, tool, arguments (including the full script code), duration, result, and for edits the change list, the undo step and the project revision. The file is rotated at 5 MB; one older file is kept.

Where to see it:

• the panel's feed, and ☰ › Activity history… (search, filters, Open log file);
• node ~/.surehand/ae/server/surehand-ae.mjs activity [n] prints the last n calls (default 30).

The log stays on your computer. Turn it off with SUREHAND_AE_NO_ACTIVITY_LOG=1 (the panel's feed is then empty).

Other logs

File	What
~/.surehand/ae/install.log	The Mac .pkg install.
~/.surehand/migration.log	The move from 1.3.
~/.surehand/ae/renders/<id>.log	aerender's output for a background render.
~/.surehand/ae/bridge-status.json	The bridge's last status: port, version, errors.
~/.surehand/ae/compat/	Reports from selftest --full.

Diagnostics collect what support needs in one report, with no secrets: ☰ › Copy diagnostics in the panel, surehand-ae diagnostics, or the report 2. Test Installation prints when a check fails.

Where your work lives

What	Where	Kept
Checkpoints	~/.surehand/ae/checkpoints/<project>-<id>/	50 per project; kept when you uninstall
Project history	~/.surehand/ae/history/	100 snapshots per project; kept when you uninstall
Proofs	~/.surehand/ae/proofs/	7 days, 30 at most; kept when you uninstall
Render profiles	~/.surehand/ae/profiles/	7 days, 30 at most
Farm manifests and plans	next to your project (<project>.farm-manifest.json / .txt, farm-plan.json, one script per machine)	yours
Handoff packages	the folder you chose (handoff.json, HANDOFF.txt)	yours
Restored checkpoints	next to your project, <project> (restored <id>).aep	yours