What the AI can do

What the AI can do

The AI works in After Effects through tools: named actions with checked parameters. There are up to 114 tools in 1.4. The README's tool list names every one; this page explains how they behave.

Tool categories

Category	Examples of what the AI can do
Scripts and workflow	Run any script; run your own .jsx / .jsxbin files; many steps as one undo step (ae_batch); checkpoints; proofs; precomp surgery
Status and app	Check the connection; switch between running After Effects versions; menu commands; undo / redo; purge; list fonts
Project	Read the project; import, organise, rename, remove items; replace footage; save, open, new project; project health; X-ray; history; color settings
Comps	List, read, create, change settings, duplicate, open, precompose, comp markers, comp map (nesting, parenting, mattes, expression links)
Layers	Read, add (solid, text, shape, null, adjustment, camera, light, footage / comp), switches, timing, parent, blend mode, track matte, order, duplicate, split, select, time remap
Properties and keyframes	Read and find properties; set values; keyframes with interpolation and easing; Graph Editor level edits (speed and influence per dimension, roving, spatial tangents, labels); copy keyframes; expressions: set, read, test, project-wide find and replace
Effects, shapes and masks	List installed effects; read an effect's exact parameters; apply, set, remove; apply a .ffx file; shapes; masks
Text	Set text; style character ranges; paragraph settings (including direction); text animators with selectors
3D	Cameras (one / two-node, focal length, depth of field), lights, material options
Audio	Convert Audio to Keyframes; markers at beats or peaks
Footage	Interpretation (conform frame rate, alpha, fields, pulldown, loop, pixel aspect), proxies, relink missing files
See and measure	Render a frame (zoom a region, solo layers, show alpha, difference image), contact sheets over time, exact layer bounds with safe-area checks, sample rendered pixel values
Essential Graphics	Add properties as controllers; export a .mogrt
Checks	Preflight against your delivery spec; stress test with worst-case inputs
Versions	Versions from data, localization, reformat, each version checked
Render	Render queue (list, add, settings, start, clear), Adobe Media Encoder queue, background renders, render profile, handoff package, farm

Comps can be named by id or name, or left out for the active comp. Layers by index (1-based) or name. Properties by paths like Transform/Position or Effects/Gaussian Blur/Blurriness.

Any language. In a non-English After Effects, English property, effect and menu names still work: Surehand maps them to After Effects' internal match names and command ids, which are the same in every language. Match names (ADBE …) always work.

Core tools and all tools

Every tool description is sent to the AI app in every chat, which costs tokens and attention. So by default only a core set of 29 tools is loaded up front (about 9k tokens instead of about 47k for all 114). Every other tool stays available: ae_tools lists all tools by category and describes any of them, and ae_call runs any tool by name, with the same checks, permissions, change report and activity log as a direct call.

The core set: ae_status, ae_run_script, ae_get_scripting_guide, ae_render_frame, ae_render_contact_sheet, ae_get_project_info, ae_get_comp_info, ae_get_layer_info, ae_get_selection, ae_get_properties, ae_find_properties, ae_get_layer_bounds, ae_get_comp_map, ae_create_comp, ae_add_layer, ae_add_shape, ae_set_property, ae_set_keyframes, ae_set_expression, ae_apply_effect, ae_get_effect_params, ae_undo, ae_batch, ae_checkpoint, ae_prove_identical, ae_list_scripts, ae_run_script_file, ae_tools, ae_call.

In AI apps that show in-chat views, the four tools with a view (ae_preflight, ae_project_xray, ae_project_history, ae_stress_test) join the core set, because a view only shows when the AI app calls the tool directly.

To load every tool up front, use one of these, then restart the AI app:

• The panel: ☰ › Tools the AI sees › All tools.
• Claude Desktop extension (.mcpb): Enable all tools in its settings.
• ~/.surehand/ae/config.json: "toolProfile": "full".
• Add single tools to the core set: "toolProfile": "core,ae_import_files,ae_render_queue_start".
• For one app only: the server option --tools full, or the environment variable SUREHAND_AE_TOOLS=full.

Order of precedence: --tools, then SUREHAND_AE_TOOLS, then toolProfile, then core.

Running scripts: ae_run_script

ae_run_script is the core feature: it runs JavaScript in After Effects, with the whole scripting API.

• The AI can write modern JavaScript (let / const, arrow functions, template strings, destructuring, classes, ?., ??, for…of, map, filter, Object.keys, JSON). Surehand converts it for After Effects' ExtendScript (ES3) engine and keeps line numbers.
• Errors come back with the failing line, the code around it and a hint.
• The script returns a value to send data back; log() output is returned too.
• Default time limit 120 seconds, up to an hour (timeoutSeconds).

Safety. A script can do anything an After Effects script can: change the project, read and write files, and run shell commands through system.callSystem. Surehand's guardrails:

• Ask mode shows you every script before it runs. See Approvals.
• ☰ › Shell commands in scripts › Off refuses scripts that call system.callSystem.
• Read-only mode refuses edits and undoes changes (below).
• Every script is in the activity log with its full code.

These are safeguards against mistakes, not a sandbox: a script can still read and write files. Only connect AI apps you trust. See Security.

Scripts that write files or use the network need Allow Scripts to Write Files and Access Network in After Effects (Settings › Scripting & Expressions). Surehand's own tools and frame previews work without it.

Every call is one undo step

Each tool call is one step in After Effects' undo history, named after the tool (for example "Surehand MCP Script"). ae_batch runs many steps (tools or scripts) as one undo step and, by default, all or nothing: if a step fails, everything is undone. ae_undo undoes the last step and reports what it reverted. It checks that After Effects really undid each step: if a dialog open in After Effects blocks Edit › Undo, it says so instead of reporting success (see Troubleshooting). You can also use Edit › Undo yourself, or Undo in the panel's feed (see The Surehand panel).

Exceptions: tools that only read add no undo step. After Effects itself can split a few operations into several undo steps (seen with comp duplicates, layer copies and source replacements); where that can happen, the result names the exact way back instead, such as a checkpoint (see Precomp surgery). Previews (frames, contact sheets) and proofs render through a temporary comp that is removed again and leave no undo step (After Effects still marks the project as changed). A script run with undoGroup: "" deliberately skips the undo group.

Tools never replace an existing file silently. ae_save_project (Save As), and the outputPath of ae_render_frame and ae_render_contact_sheet, refuse when a file is there, unless the AI passes overwrite: true.

Change reports

Every call that edits the project ends with a Changes list, computed by After Effects itself from a snapshot before and after the call:

Changes (layers/properties compared in: Main):
+ layer "Headline" in "Main"
~ layer "Plate" in "Main": name "Plate" -> "Background"; locked off -> on
+ Headline > Effects/Glow
~ Headline > Transform/Opacity: 100 -> 0, expression added
~ Headline > Transform/Position: [640,360] -> [640,800], keyframes 0 -> 2

• Project items are always compared. Layers, properties, keyframes, expressions, effects and masks are compared in the active comp and any comp named in the call.
• If a script fails halfway, the report lists what it had already changed.
• The panel shows the first lines in the feed; Details shows all.
• On very large comps (tens of thousands of properties) this adds up to about a second per edit. Turn it off with "changeReport": false in config.json, or per script with report: false.

Read-only mode

In Read-only mode (see The Surehand panel):

• Editing tools are refused with "Surehand MCP is in read-only mode, so tools that change the project are disabled."
• Reading tools, previews, proofs (capture and compare), Preflight, X-ray and history work.
• Scripts still run, to read information. Each runs in its own undo group and is compared with the project before; if it changed anything, it is undone at once and the AI is told what it tried to change.
• Some scripts are refused before they run, because their effect can't be undone reliably: calls that touch the undo history (executeCommand, beginUndoGroup, endUndoGroup, purge), open, close or save projects (app.open, openFast, newProject, project.close, save, saveWithDialog), quit, rendering (render), scheduleTask, and saving preferences (savePrefAs…, saveSetting, saveToDisk).

This check reads the code text: comments are ignored, escapes are decoded, and a name inside a string or on another object counts too. A call assembled at runtime gets past the text check; it is then undone like any other change (at most once, checked with a temporary undo marker), and reported if the project isn't back.

Your own scripts

ae_list_scripts lists the scripts in After Effects' Scripts folder (and ScriptUI Panels), plus folders you add as "scriptFolders": ["/path/to/scripts"] in config.json, with each script's description from its header comment. ae_run_script_file runs one, with arguments.

Precision tools

Keyframe tables in frames, exact ease copying and audits, retiming on whole frames, layout from measured bounds, finding files and exporting stills: see Precision tools.

Text direction

Text the AI adds or sets with Surehand's text tools is set left to right, whatever your After Effects type preference says, unless the text contains Hebrew or Arabic characters. The AI can set the direction explicitly (direction: "LEFT_TO_RIGHT" or "RIGHT_TO_LEFT", After Effects 24 or later). For translated versions, see Localization.

Seeing and measuring

• ae_render_frame: one frame as an image. It can zoom into a region, render only some layers, show transparency on a checkerboard or a color, or make a difference image against another time or comp.
• ae_render_contact_sheet: a grid of frames across time, labelled with time and frame number, to judge motion and easing.
• ae_get_layer_bounds: exact on-screen boxes after transforms, parenting, 3D and camera, with in-frame and action / title-safe checks.
• ae_sample_pixels: rendered RGBA / hex values at points.

Example requests

• "Make a 10 second 1080p comp with a dark background and the title 'Summer Sale' that scales in with an overshoot, then show me frame 1s."
• "List every expression in the active comp that has an error and fix them."
• "Rename all layers in the selected comp to Title Case and color-label text layers yellow."
• "Un-precompose 'Logo Precomp' into the main comp and prove the render didn't change."
• "Stress-test the lower third with long German names and Arabic."
• "Make a 9:16 of Promo. Logo pinned 80 px from the top, titles inside title-safe."
• "Import /Users/me/footage/*.mov, make a comp for each clip and add them all to the render queue."