Execute JavaScript inside After Effects (its ExtendScript scripting API) and return the result. This is the most powerful tool: anything in the After Effects scripting API is available (app, app.project, CompItem, layers, properties, render queue, File/Folder, system.callSystem...).

• The code runs as the body of a function: use return value to send data back. Returned AE objects (comps, layers, properties, items) are summarized to JSON automatically.

• args (the JSON you pass in args) and log(...) are available; log output is returned too.

• Modern JavaScript is fine: let/const, arrow functions, template strings, destructuring, spread, classes, ?. and ??, for...of, plus map/filter/forEach/find/includes, Object.keys/assign and JSON (converted for AE automatically). Not available: async/await, Promise, Map/Set, generators.

• The aemcp helper library is available: aemcp.findComp(idOrName), aemcp.findLayer(comp, indexOrName), aemcp.findItem(ref), aemcp.resolveProp(layer, 'Transform/Position'), aemcp.color('#ff0000'), aemcp.compInfo(comp, true), aemcp.layerInfo(layer, true), aemcp.propInfo(prop, {depth:2}), aemcp.projectInfo().

• Collections are 1-based: app.project.item(1), comp.layer(1), prop.property(1).

• The whole script is one undo step. Errors come back with the failing line and code around it. ae_get_scripting_guide has an API cheat sheet.

• Prefer the dedicated tools for common edits (clearer validation and results); use this for anything they don't cover. For a script file on disk use ae_run_script_file.

Run an existing .jsx/.jsxbin script file from disk inside After Effects (like File > Scripts > Run Script File), e.g. one found with ae_list_scripts. args is exposed to the script as the global AEMCP_ARGS. Returns the value of the script's last expression and a change report; the run is one undo step. A missing file is an error; refused in Read-only mode. For code you write yourself use ae_run_script.

Check the connection to After Effects: app version, OS, open project, active item, permission mode, and whether AE is busy. Lists every running After Effects instance when several are open; pass instance (e.g. "2025", "2026" or a port) to choose which one this session controls. Call this first if unsure AE is reachable; if it isn't, the error says why (e.g. not running, or not taking scripts). For the project's contents use ae_get_project_info.

Render a frame of a composition and return it as an image, so you can SEE the result. Inspection options: zoom into a region, render only some layers, show transparency on a checkerboard or a color, and compare against another time or comp as a difference image (black = identical). Large frames are downscaled to maxSize. Use it after visual edits; for motion use ae_render_contact_sheet, for exact colors ae_sample_pixels (via ae_call). Renders through a temporary comp, removed afterwards (hidden layers put back); writes a file only with outputPath, never replacing one unless overwrite.

Render several frames of a composition into ONE image (a grid, each cell labelled with its time and frame number), so you can judge motion, timing and easing, not just a single frame. Defaults to 9 frames spread over the work area. For one frame in detail use ae_render_frame. Writes a file only with outputPath, never replacing one unless overwrite.

Summary of the open project: file path (null if never saved), unsaved-changes (dirty) state, item counts by type, bit depth, render queue size, active item. Read-only and quick: call it first to orient. For the connection and permission mode use ae_status; to list comps or items ae_list_comps / ae_list_items, for problems ae_project_health, for how a project works ae_project_xray (all via ae_call).

Composition settings and markers plus a summary of its layers (index, id, name, type, timing, parent, switches). Large comps are paged: use layerOffset/layerLimit (see totalLayers / nextLayerOffset in the result). Read-only. Use it to see what a comp contains; for one layer in full use ae_get_layer_info, for nested precomps, parenting and expression links ae_get_comp_map.

Create a new, empty composition in the open project and (by default) open it in the viewer. Returns the new comp's id, name and settings: pass the id as comp to later calls (names need not be unique). Then add layers with ae_add_layer / ae_add_shape. To copy an existing comp use ae_duplicate_comp, to move existing layers into a new comp ae_precompose (both via ae_call).

Full info for one layer: switches, timing, parent, source, transform values, effects, mask count, markers, text, and every animated/expression property. Read-only; fails if the comp or layer isn't found. For all layers in brief use ae_get_comp_info, for the full property tree (paths to set) ae_get_properties, for the on-screen box ae_get_layer_bounds.

Add one new layer to a composition: solid, text, shape (empty, use ae_add_shape to draw), null, adjustment, camera, light, or an existing project item (footage/comp). Each call adds another layer, on top unless moveToIndex is given. Returns the new layer's index, id and name. Text options apply to text layers only. To edit existing text use ae_set_text, for switches, timing or parent ae_set_layer_attributes (both via ae_call).

What the user has selected right now: project items, and in the active comp the selected layers and selected properties (with paths usable by ae_set_property). Read-only. Use it when the user says "this layer" or "the selected ones". Lists are empty when nothing is selected, and comp is null when no comp is active. To change the selection use ae_select_layers (via ae_call).

Inspect the property tree of one layer (or a sub-group via path): names, match names, values, keyframe counts, expressions. Read-only. Use it to discover property paths before ae_set_property / ae_set_keyframes / ae_set_expression. To search a whole comp by name use ae_find_properties; for exact keyframe timing and easing use ae_get_keyframes (via ae_call). Large trees are truncated: lower depth or start at a path.

Search every layer of a comp (or one layer) for properties whose name or match name contains the query, e.g. "opacity", "blur", "Source Text", "ADBE Fill Color". Returns ready-to-use paths with values (and expressions with their errors). Filter to animated or expression properties. Needs a query or a filter; stops at limit and sets truncated. Read-only. Use it when you know a property's name but not its layer or path; to browse one layer's tree use ae_get_properties.

Set the value of any property (transform, effect parameter, shape attribute, text...). If time is given (or the property already has keyframes) a keyframe is set at that time. Examples: path "Transform/Opacity" value 50; "Transform/Position" [960,540]; "Transform/Scale" [50,50]; "Effects/Fill/Color" "#ff0000". Returns the property's new state; fails if the path is a group or not found. For several keyframes with easing use ae_set_keyframes, for expressions ae_set_expression, for many parameters of one effect ae_set_effect_params (via ae_call).

Create keyframes on a property in one call, with optional interpolation (linear/bezier/hold) and temporal easing. Place keys by time (seconds) or frame (whole frames). Example: path "Transform/Position", keyframes [{time:0,value:[0,540]},{frame:24,value:[960,540],easeIn:80}]. A key at a time that already has one replaces it; other existing keys stay unless clearExisting. Returns the property's keyframes. For one static value use ae_set_property; to edit existing keys ae_edit_keyframes, for exact tables across many properties ae_set_keyframe_table (both via ae_call).

Set, replace or clear (empty string) the expression on one property. Returns the expression, whether it is enabled, any error AE reports and the resulting value at the current time. To try an expression without keeping it use ae_check_expression, to edit text across many expressions ae_replace_in_expressions, to list them ae_get_expressions (all via ae_call).

List an effect's parameters (names, match names, value types, defaults, min/max) so you know the exact parameter names for ae_apply_effect / ae_set_effect_params (via ae_call). By default it reads a fresh instance: it applies the effect on a temporary comp and removes that comp again in the same undo step, so your comps and layers are left as they were. Pass comp+layer to read an effect already applied to that layer instead (current values). Unknown effect names fail with suggestions.

Apply an effect to a layer by match name (preferred, e.g. "ADBE Gaussian Blur 2", "ADBE Fill", "ADBE Glo2", "ADBE Drop Shadow") or display name, optionally setting parameters. Each call adds a new instance at the bottom of the layer's effect stack. Returns its index in the stack, its parameters and the values set; an unknown effect name fails with suggestions. Check parameter names first with ae_get_effect_params; change an applied effect with ae_set_effect_params, search installed effects with ae_list_available_effects (both via ae_call).

Draw a shape (rectangle, ellipse, polygon, star, or custom path) with fill and/or stroke, as a new shape group on a new shape layer or added to an existing shape layer (its other groups are kept). Positions are relative to the layer (new layers are centered in the comp, so [0,0] is the comp center). Returns the layer and the new group. To cut out part of a layer use ae_add_mask (via ae_call).

Undo the last action(s) in After Effects, like Edit > Undo; each Surehand MCP edit call (an ae_batch included) is one undo step. Returns how many steps were undone and a change report across all comps. If After Effects undoes nothing (nothing left to undo, or a dialog open in After Effects) it fails and says so. Reverse it with ae_redo (via ae_call); to go back further, restore an ae_checkpoint.

Exact on-screen bounding boxes of layers in composition pixels at a time, after all transforms, parenting, 3D and the active camera (via AE's own toComp()). Also reports whether each layer is visible at that time, fully/partly/not in frame, and inside action-safe (5% margin) and title-safe (10% margin). Use it to check alignment, spacing, overlaps and safe areas with numbers; to move layers by these bounds use ae_align_layers (via ae_call). It measures through a temporary probe layer removed in the same undo step; your layers are left as they were.

Overview of how a composition is built: the tree of nested precomps (with how many times each is used), parenting chains, track mattes, and which layers/comps each expression references. Read-only. Use it to understand an unfamiliar comp before editing; for one comp's settings and layer list use ae_get_comp_info, for the whole project (render queue, missing items, fragile links) ae_project_xray (via ae_call).

Run many steps in ONE call: each step is a tool with its arguments (any project/comp/layer/property/keyframe/effect/text/footage tool) or {tool: "ae_run_script", args: {code}}. All steps form a single undo step and return one change report. Atomic by default: if any step fails, everything is undone and you get the error of the failing step. Use it for repetitive or multi-part edits (e.g. style 30 layers, build a scene) to save round trips; for a single edit call the tool directly. Not usable as steps: tools that can't be part of an undo step (open/save project, undo/redo), renders and ae_checkpoint.

Safety copies of the project: save (saves the open project, then keeps a timestamped copy), list the checkpoints of this project, or restore one (opens it as a NEW file next to the original; neither the original nor an earlier restore is ever overwritten). Use before large or risky changes. The project must have been saved once. save returns the checkpoint id and file; list the ids, times and labels; restore without id takes the latest and refuses while the open project has unsaved changes unless discardChanges. Keeps the 50 latest. To revert just the last edits use ae_undo.

List the user's own After Effects scripts: AE's Scripts folder (and ScriptUI Panels) plus folders configured as "scriptFolders" in ~/.surehand/ae/config.json, with each script's name, path, kind (script or panel) and description from its header comment. Needs After Effects running (to find its Scripts folder). Run one with ae_run_script_file; for code you write yourself use ae_run_script.

Prove a structural change (un-precompose, bake expressions, reorder effects, simplify a rig) left the render unchanged, or show which frames and areas differ. capture: render reference frames (default: active comp, 5 frames over the work area), returns a proof id. compare: render them again and compare pixel by pixel (verdict, per-frame max difference, changed pixels, ΔE, area, difference image). run: capture, ae_batch steps, compare, in one call. For un-precompose, prove the parent comp. Not for edits meant to change the picture (look at those with ae_render_frame). Only the sampled video frames are compared (alpha included; not audio, the comp background color or times between samples; 32 bpc values above 1.0 are clamped).

Returns the After Effects ExtendScript cheat sheet (ES3 rules, helpers, common match names). Read before writing complex ae_run_script code; not needed for the dedicated tools.

Discover every After Effects tool, including ones not loaded in this chat: list them by category (one line each), or describe chosen tools (full parameters, up to 10). Then run any of them with ae_call. Tools already loaded here need no lookup: call them directly. Categories: status & app, scripts, project, comps, layers, properties & keyframes, effects, shapes & masks, text, 3D, audio, footage, files & export, checks, see & measure, essential graphics, render.

Run any After Effects tool by name with its arguments, e.g. tools listed by ae_tools that aren't loaded in this chat. Same validation, permissions, change report and activity log as calling the tool directly. Get the parameters with ae_tools {describe: [name]}. Invalid arguments come back as an error listing them. Tools loaded in this chat don't need it: call them directly.