npm.io
0.7.0 • Published 3 weeks agoCLI

pixelate-mcp

Licence
MIT
Version
0.7.0
Deps
2
Size
223 kB
Vulns
1
Weekly
0

PixelAOI MCP

An MCP server that lets an AI agent (Claude Code, Codex, Cursor, Claude Desktop) work in the PixelAOI pixel-art editor: see the canvas, paint it, arrange layers, build animations, apply filters and adjustment layers, pixelate images, and wire Blueprint node graphs.

Everything runs on your machine: the server talks to the editor over a localhost-only link (127.0.0.1). No cloud, no accounts, no API keys.

Requires PixelAOI 0.6.0 or newer (with the agent token handshake) and pixelate-mcp 0.7.0 or newer. Older pixelate-mcp versions don't say hello with the token, and every call fails with "say hello with the bridge token first": update with npx -y pixelate-mcp@latest.

Click agent off in PixelAOI's status bar (bottom right). It turns to agent ready while it waits, and agent live once your agent connects. Click it again to turn it off: that cuts the agent off at once and stops listening. Whatever it asked for that PixelAOI hadn't run yet is dropped, not run later, the token file is deleted, and its calls fail until you turn the link back on. (Or start PixelAOI with PIXELAOI_AGENT_BRIDGE=1, which turns it on from the start.) If it says agent: port busy (retrying), something else holds the port. PixelAOI tries it again every few seconds, so a port held for a moment frees itself; if another PixelAOI holds it, close that one.

One agent at a time: an agent that connects with the token takes over, and the one before it is disconnected (its calls fail with "the link to PixelAOI closed"). A connection without the token can't disturb the agent.

The token

Anything on your computer can open a connection to 127.0.0.1, so PixelAOI doesn't take orders from just any of them. Each time the link turns on, it writes a fresh random token to agent-bridge-token in your user's PixelAOI data folder. Whatever can read that file can drive the editor, so PixelAOI writes it for your user only (on macOS and Linux only your user can read it; on Windows it lives in your own %LOCALAPPDATA%):

Windows %LOCALAPPDATA%\pixelaoi\agent-bridge-token
macOS ~/Library/Application Support/pixelaoi/agent-bridge-token
Linux ~/.local/share/pixelaoi/agent-bridge-token (under $XDG_DATA_HOME when that is set)

On Linux, when the server's $XDG_DATA_HOME has no token there, it also looks in ~/.local/share/pixelaoi: an agent host packaged as a Flatpak or Snap starts the server with the sandbox's own XDG_DATA_HOME, while PixelAOI wrote its token in the usual place.

With PIXELAOI_PROFILE set, the folder is pixelaoi/profiles/<name>, so give the server the same PIXELAOI_PROFILE as the editor. On a port moved with PIXELAOI_BRIDGE_PORT the file is agent-bridge-token-<port>, so two PixelAOIs on two ports each keep their own. The server reads the file every time it connects and sends the token as its first line, {"id":0,"op":"hello","args":{"token":"…"}}; PixelAOI answers nothing else until it has seen it. You never copy it by hand. (To give it yourself, set PIXELAOI_BRIDGE_TOKEN.)

2. Add the server to your agent

Claude Code
claude mcp add pixelaoi -- npx -y pixelate-mcp
Codex (~/.codex/config.toml)
[mcp_servers.pixelaoi]
command = "npx"
args = ["-y", "pixelate-mcp"]
Claude Desktop / Cursor (JSON config)
{
  "mcpServers": {
    "pixelaoi": { "command": "npx", "args": ["-y", "pixelate-mcp"] }
  }
}

Restart the agent, make sure PixelAOI says agent ready, and ask it to draw something. The server shows up as PixelAOI, with the PixelAOI mark (in colours for light and dark clients), and tells the agent how to work with the editor when it connects.

Tools

Each tool has a title your client can show, and says whether it only reads or changes the document, so a client can let reads through and ask before changes.

Each change to the document is one undo step in PixelAOI, with a name, and run_command undo takes the last one back: each set_canvas_image or set_pixels paint (an image opened as a new document is a new tab instead), a filter, a layer change, a new frame, an add_tag, a render_model (a sprite_size other than the sprite's is a Sprite size step of its own before it), a change of the sun or the shade (model_light). Edits to a Blueprint graph's nodes and wires are outside it. The 3D model has Model mode's own undo: each change to it (new_model, model_character, model_shape, model_carve, model_part, model_pose, rig_model, model_action, model_light's lamps, model_reference, scale_model, model_colour) is one step there, named for what it did (Agent: keys on Arm L: the result's undo_label), as is the sprite camera a render_model sets (Agent: sprite camera, from its angle, tilt or directions), and the user takes it back with Ctrl+Z in Model mode, whether the mode was open (it stays open, and the change shows at once) or shut. run_command undo is the document's: it is refused while Model mode is open and never takes back a model change.

Tool Title
get_state Editor state reads
get_canvas_image See the canvas reads
run_command Run a command changes
apply_filter Apply a filter changes
layers Arrange layers changes
adjustment_layer Adjustment layers changes
set_canvas_image Paint an image changes
set_pixels Paint pixels changes
pixelate_image Pixelate an image changes (may fetch a URL)
extrude_animate 3D turntable changes
add_frame Add a frame adds
select_frame Show a frame adds
set_frame_duration Frame timing changes
add_tag Tag frames adds
save_document Save the project changes
close_document Close the document changes
blueprint_node_kinds Blueprint node kinds reads
blueprint_list Read the Blueprint reads
blueprint_select_graph Switch Blueprint graph adds
blueprint_add_node Add a node adds
blueprint_connect Connect nodes adds
blueprint_connect_value Drive a parameter adds
blueprint_set_param Set a parameter changes
blueprint_set_data Set node data changes
blueprint_delete_node Delete a node changes
blueprint_bake Bake the Blueprint changes
get_model Read the 3D model reads
look_model Look at the 3D model reads
check_model Check the 3D model reads
new_model Start a 3D model changes
model_shape Build the 3D model changes
model_carve Carve a 3D part changes
model_character Make a 3D character changes
model_part Rig a 3D part changes
model_pose Pose the 3D model changes
rig_model Rig the 3D model changes
model_action Actions of the 3D model changes
model_light Light the 3D model changes
model_reference Reference drawings of the 3D model changes
scale_model Scale the 3D model changes
model_colour Colour the 3D model changes
render_model Render the 3D model adds
export_model Export the 3D model writes a file

In more detail:

  • get_state: canvas size, frames, the layer stack (each layer's index and uid, each folder's id), the selection, the tool, the palette, the Blueprint editor's state, and the command names run_command takes.

  • get_canvas_image: the current frame as PixelAOI shows it, as a PNG.

  • run_command { action }: a command by name (flip_h, rotate_90, trim, undo, save, ...). A filter's name (invert, blur, ...) applies it at once with its remembered settings.

  • apply_filter { name, params?, output?, frames? }: a filter on the active layer as one undo step: blur, hsl_adjust, levels, outline, drop_shadow, color_reduce, ... params by the labels PixelAOI shows ({"Radius": 3}, {"Hue": 30}) or in order; output pixels (default), new_layer or adjustment (an adjustment layer doing it live, with affects layer or below); frames this (default), selected or all. A selection limits it. Curves takes points per channel, {"all": [[input, output], ...], "red": ...}, and Gradient Map a ramp, {"stops": [[position, r, g, b], ...]} (0-255, at most 16 points or stops).

  • adjustment_layer { action, kind?, params?, affects?, enabled?, item? }: layers with no art of their own that change what is under them, live: add, set, remove, bake.

  • layers { action, items?, … }: select, move, group, ungroup, new_folder, set (visible, locked, opacity, blend, draft, clipping, expanded, name), delete, duplicate, merge. A layer by its index, {layer: i} or {uid: "…"}; a folder by {folder: id}; no items means the selection.

  • set_canvas_image { image_path | png_base64, as_new_document?, name? }: paint an image; at the canvas's size it paints the open document, otherwise it opens as a new one. At most 4096 pixels a side.

  • set_pixels { x, y, w, h, rgba_base64 }: a raw RGBA block, clipped to the canvas (at most 4096 pixels a side). Each paint is its own undo step.

  • pixelate_image: any image (path, base64 or URL) into grid-perfect pixel art with PixelAOI's own engine (it finds the native grid and palette), then painted in. colors is a palette size up to 256 (PixelAOI uses at least 2); left out, the palette is found too. A URL must answer within 30 s with at most 64 MB; an HTTP error comes back as its status.

  • extrude_animate: a 3D extrusion turntable of the canvas across the timeline.

  • add_frame, select_frame { index }, set_frame_duration { index?, duration_ms }, add_tag { name, from, to? }: build an animation (frames from 0; 10-10000 ms a frame).

  • save_document { path }: save as a .pxl project at an absolute path; close_document: close the tab once saved (refused while unsaved).

  • Blueprints: switch the graph (Particle, Canvas, Ai, Layer), list the node kinds, add, wire (output to input, or a value node driving a parameter), set parameters and node data, delete, and bake the result into the document. In an Ai graph an AI Result Source can feed an AI Generate or an AI Prompt, to chain one generation into the next; a wire that would close a loop is refused. A bake with nothing to bake (no output wired, say) is an error saying why; an AI bake answers once its generations have started, and their images land when they arrive.

  • 3D models (Sprite › 3D Model in PixelAOI; a block is one unit, y is up and the front faces +z): get_model reads the open sprite's model (its box in blocks; its parts with their blocks, the box they span, pivot, parent and whether they are locked, each one's mirror (its own Mirror X, Y and Z), its twin (by name, or null), its rest (its turn and move with no key), whether it is a control, its depth and order in the parts tree, and the tree itself as Model mode's PARTS shows it, each part after the part it goes with, and outline: false on a part the PART card's Outline draws without its outline; its actions, each with its frames, frame_ms, loop, the parts it keys, its steps (free, or 8, 16 or 32 a turn) and whole_pixels (and, where it has them, its holds as [frame, times] and its kept_keys, the keys kept past its end), and the one on show; its lamps; and the mirror plane, mirror_at ([x, y, z] in blocks, the box's middle until it is moved)), or null. look_model { view?, action?, frame?, direction?, angle?, tilt?, directions?, zoom?, isolate?, rest? } shows it as a PNG, changing nothing: one action on one frame from one direction (S … SSE, or all for every direction of the sheet side by side), in the Sprite view (the sprite as a render makes it, at its own size) or the Build view (its blocks, the whole box in view), scaled up by whole pixels (zoom 1-8, lowered where it would pass 2048 a side, never below 1: all on many directions or a big sprite is a wide picture, one direction keeps it small). It looks through the model's own sprite camera (with Model mode open, the one its header's SPRITE cluster shows), or the angle (bottom looks up at the underside), tilt and directions (2-64) asked, set nowhere. A tilt names its style, as one typed in Model mode's header does (0 side, 90 top, -90 bottom, else three_quarter), so side, top or bottom asked with a tilt not theirs is refused, as render_model refuses it; the answer's angle and tilt say the camera it looked from. isolate (a part's name, or a list of them) shows those parts as they are and the rest at 20%, as Model mode's Isolate draws them, to see a part inside or behind others; the answer names them in isolated. A hidden part is refused, as Isolate refuses it. rest: true shows the rest pose, the model with no key as Model mode's Rig stage and Build's REST show it (every action's: frame and action are refused with it, and the answer's rest is true, its frame and action null). check_model { dismissed? } says what will look broken once the model is posed and rendered, as Model mode's CHECK finds it, changing nothing: a part that only touches what it goes with at a corner, stands apart from it, or meets it flush where it bends (posing opens a gap; the fix is Overlap the joint); a part one block thick that turns, at a pixel a block; a part going with nothing beside a part that moves (it stays behind); an action whose different keys land on one step; a one-block detail that drops out in some directions on the frames a render makes; a part reaching past the frame; and, as notes, two parts named for each other's side (Arm L and Arm R) that aren't twins (not_twins) and Rig it's guesses. Each row has its kind, its text (the words the list shows), the part, action and frame it is about, its fix (do: overlap, keep_details, steps, go_with or pair_by_names, the button's label, and what it is carried out with: action and steps, free or a count, for model_action set; with, the part to go with for model_part's parent, or the part overlapped; pair_by_names is model_part's pair_by_names: true, which links every such pair; Overlap the joint and Keep 1-block details are the user's buttons, and render_model's keep_details keeps details in one render), note and dismissed; count is the warnings to look at. Rows dismissed on the model are left out unless dismissed is true. new_model { width?, height?, depth?, starter?, vox_path?, vox_base64?, example? } gives the sprite a new, empty model (1-512 blocks a side), the starter house or one of Model mode's Examples… by name (Oak, Fox..., as it is), in place of the one it has, or brings a .vox file in as Import does: each object a part placed where its scene graph puts it (moved, turned, in its groups), named as its object is (else Vox 1, Vox 2... by its model), hidden when its object or its layer is, in a box that holds them all (a file without a scene graph stacks its models at their own corners); no size or starter goes with it, and a file of no blocks is refused. The answer's note says when a scene came in otherwise than placed: one wider than a model holds (512 a side) comes in stacked, every voxel kept; one placing more than 256 objects, its first

    1. A .vox or an example replaces the model: Import's join of a file's objects beside the model's parts, and Examples…' Add as parts, are the user's. model_shape { shape?, from, to?, sides?, face?, depth?, plane?, facing?, radius?, thickness?, colour?, op?, part?, smooth?, twin_mirror? } adds, erases or paints a box, rounded box, ball, cylinder, cone, ramp, roof or ring between two corner blocks, in a named part (a new part's name is at most 40 characters). The box can also be given as Model mode's Box and Shape drags set it: from and its sides typed ([x, y, z] blocks, a negative one the other way), a footprint from-to on one layer pulled out face (+x, -x, +y or up, -y or down, +z, -z) depth layers or "auto" (the footprint's shorter side), or a footprint on a work plane, plane { axis, layer } (pulled toward the axis's + side unless face says the other way, a layer thick unless depth says more). facing turns a ramp (north, east, south, west: the side it rises to), a roof (x, z: its ridge), a cylinder or a ring (x, y, z) or a cone (its tip, +y, -y, +x ...); radius rounds a rounded box (1-4) and thickness sets a ring's tube (0.1-1 of its radius). The answer says the box drawn: from, to and sides. On a part with a twin, what is drawn lands mirrored on the twin too, in the same step, as Model mode's twin mirror has it (a block added where the twin's cell is empty, a paint only on the twin's own blocks and only on the faces painted); twin_mirror: false keeps it on the part alone. The answer's twin and twin_changed say what changed there, twin_missed and a note what couldn't land (outside the box, or the model full) or why nothing did (left alone, or locked). A model with twins keeps its x plane where they stand mirrored as the box grows.
  • model_carve { views, depth?, outline?, part?, at?, new_model?, smooth?, back?, bottom? } carves a part from drawings, a pixel a block, as Model mode's Carve does: views is one to six { view, image_path | png_base64, flip? } (front, back, left, right or side, top, bottom), each drawn as seen from its side. A block is solid where every drawing has a pixel, and each face takes the colour of the drawing looking at it. It goes in as a new part (centred on the floor, or its low corner at at), into the part part names (carved again in the box it was carved in, centred there on its floor, as Model mode's Remake carves it, the overlap its joint had made again; one with no box kept, or turned or scaled since, where it stands; its pivot, keys and parent kept; a new name is at most 40 characters), or as a new model of it alone (a part with a twin is carved alone, as the Carve card carves it: model_part's update_from brings the twin along); the box grows to hold it and nothing else moves. With no back drawn, back says how the back is coloured: sides (the default: each row takes the colour the side drawings show at their back edge, so hair stays hair round the back of a head, whatever shade the top draws it in), mirrored (the front seen through, its face too; with no front drawn, the right side's, else the top's, the left's or the bottom's, the first of those drawn) or plain (one colour); bottom the same for an undrawn bottom (sides: the lowest row of the drawings beside it; mirrored: the top seen through, and with no top drawn the front's, else the right side's, the back's or the left's, the first of those drawn). The answer's back and bottom say what an undrawn one took (back_from and bottom_from: the drawing a mirrored one took where the one opposite isn't drawn either), and the part keeps it for Re-carve. A character carves in one call from the open sprite's layer folders instead, as Model mode's Carve a character does: { folders, place?, on?, at?, depth?, outline?, new_model?, back?, bottom? }, folders true (every folder whose layers are named for the views they show: front, side, top...) or the folders' names. Each folder (Head, Body, Arm L...) is a part named after it, carved from its own layers; the parts line up as they are drawn on the canvas (each part's front where it stands in the character's front, each side where it stands in its side) and are rigged among themselves as rig_model rigs them (what goes with what, pivots at the joints, joints overlapping, IK on two-part limbs). The character goes in place drawn (the default: lined up with the parts carved from the sprite's layers before; with none, centred on the floor) or floor (the box grown about its middle where it must, as the card's Floor middle grows it); on a part (standing on its top, centred, its root going with it; one folder's part turning about its bottom's middle); its low corner at; or as a new model. part and smooth are one part's, and refused with folders. The answer lists each part (blocks, box, goes_with, pivot), the root, ik_limbs and moved (how far the model moved over to make room). One undo step, Agent: carve a character (Agent: new model from a character carve with new_model, or when the sprite has no model yet).

  • model_character { plan, height?, thickness?, head?, body?, arms?, legs?, ears?, tail?, joints?, colours?, into? } makes a rigged voxel character to start from, already walking, as Model mode's New › Character does: plan is chibi (a fox kit, about 2½ heads), tall (a hare), four_legs (a fawn), round (an owl), small (a hedgehog) or heavy (a bear), or the animal's name (fox_kit, hare...). Its parts are named Hips (a control: no blocks, the root that carries the whole character), Pelvis (the hips' blocks, going with Hips), Body, Head, Ear L/R, Arm L/R (the owl's Wing L/R), Leg L/R, Tail (on four legs Front leg L/R and Back leg L/R) and Eyes shut (a blink's lids, going with Head: resting hidden, shown on Idle's frame before its last); Body and the legs go with Pelvis (on four legs the back legs and the tail; the front legs go with Body, and on two legs the tail too). Every L/R pair comes linked as twins (get_model's twin), the mirror plane at the body's middle, so what model_shape draws or model_colour shades on one lands mirrored on the other, and a pivot model_part gives one moves the other's, unless twin_mirror is false (added as parts, a pair stays twins only where it still mirrors across the model's plane). joints knees_and_elbows puts each long enough limb in two parts (Forearm, Shin, Front shin, Back shin), and is refused, saying why, where no limb would bend: the owl keeps each limb in one part (its wings fold whole and its legs step without a knee), the hedgehog each leg. Each goes with the part it hangs from and turns about its joint, which overlaps a block so a bend never opens a gap; it faces +z, so the S sprite shows its face, and comes with Idle (a breath a second and a blink, 4 frames at 4 fps) and Walk at 12 fps (Walk on show). The sizes are blocks as the tab shows them: height (16-48) and thickness (2-4: a one-block limb breaks into dots as it turns) first (the rest then within what they leave, as the tab takes them), then head, body (its width), arms (front legs, wings), legs (back legs) and ears, set together as named, in any order, the ones not named making room where they must, as the tab's sliders do (an error names the first one named that can't be, and its reach with the others named). tail is none, short or long; colours { fur?, belly?, dark? } are #rrggbb. into new_model (the default) replaces the model; parts adds its parts beside the model's (taken names get a number; its Walk joins the action on show, a namesake its namesake, the rest come as their own: actions_joined). The box grows to hold them, both ways across a plane the model mirrors across (a character's Head and Body mirror x), the model's own parts and lamps moving over with it: moved says how far, [dx, dy, dz] (left out when nothing moved), and the answer's model gives their new boxes; where only a box grown one way would fit (past 512 both ways), it is refused, naming the parts that mirror. The sprite keeps its size: sprite_fit is the size that holds every pose.

  • model_part { part?, parts?, action?, split_from?, region?, goes_with?, copy?, merge_down?, merge_into?, outline?, joint?, copy_keys?, pivot?, parent?, keys?, tracks?, smooth?, visible?, locked?, delete?, rest_turn?, rest_move?, rest_from_frame?, reset?, control?, frames?, frame_ms?, loop?, mirror_part?, twin?, update_from?, update?, pair_by_names?, mirror_plane?, axis?, twin_mirror?, limits?, chain?, shown?, rest_shown?, swap_with?, leave_swap?, socket?, held_by?, export_point? } rigs and animates (locked keeps Model mode's tools, model_shape and model_carve off a part; parts, in place of part, names several at once, as picking them in PARTS does, and visible, locked, parent, delete, reset or rest_from_frame act on every one as one undo step whose pill counts them: Agent · 3 parts locked; the action's motion, frames, frame_ms and loop, goes in a call without parts). copy: true puts a copy just after the part (Roof copy, its keys in every action); merge_down: true merges it into the part after it in the tree, and merge_into into the part named (its blocks where they stand in the model; what went with it goes with that part); outline false draws it without its outline (no line on it or round it: eyes and small gear), true with. Each of the four is given alone with part (any other key refused), one step. The rest pose is where a part stands with no key: rest_turn and rest_move ([x, y, z], degrees and blocks) set it, as the PART card's REST numbers do, and every action's keys of the part are worked out about the new rest, so its motion keeps its shape, while everything that goes with it is carried with it at rest and on every frame (the answer's rekeyed says whether keys changed, for rest_from_frame and reset too; rest_move is -1024 to 1024 blocks on each axis; not with keys or tracks in the same call; keys worked out again keep within each part's joint limits about its new rest, the answer's limited saying when they held any back). rest_from_frame makes a frame's pose (of action, as it draws it: its turns on its steps, its moves on whole pixels) the rest, its keys as they were (its joint limits' ranges moving with the rest) and what goes with it staying where it stands (a part going with it keeps within its own joint limits, limited saying so); it is refused, changing nothing, where a frame would then draw a step or a pixel off (a turn exactly half a step from two drawings, or an action on other steps), the error naming the frame; reset keys each property it has keys on at its rest on a frame (no step when it stands at rest there). control: true makes a control, a part with no blocks that carries what goes with it and renders nothing: by a new part's name it is made, and an empty part's name makes it one, its pivot on the floor's middle unless pivot says (a template's Hips is one; its blocks are the Pelvis that goes with it). get_model gives each part's rest ({ turn, move }) and whether it is a control. split_from + region ({ from, to, shape?: box | ball | cylinder, axis? }) takes a part's blocks into a new part, rigged as Model mode's Split off rigs it (a wheel: a cylinder along x). It goes with the part it came from (goes_with, default true; false: with what that part goes with), turns about the joint where they touched (pivot defaults to joint; a point is put where its blocks stay) and has no turn or move keys (going with its part it takes the part's Shown keys, so a piece of a blink still blinks; copy_keys, with goes_with false, takes that part's keys in every action, and its pivot). joint is how it meets that part: overlap (the default about the joint) keeps a copy of the touching layer inside it, hidden at rest, so a bend never opens a gap; flush is a plain cut (the default about anything else, a wheel at its centre, and where they don't meet face to face); rounded trims its end round the joint (with pivot joint, and an end of it facing that part: not a limb lying along it). A joint that can't be made is refused; with nothing of that part within 8 blocks it turns about its centre (joint is refused then). Left out, part is named by where it sits (Head above, Arm L or Arm R at the sides, Leg L or Leg R below, Tail behind), and the answer's part and split say what it made (split: its pivot, the preset that put it there as pivot_at, the joint made, a joint that made nothing being flush, whether it met that part, how many blocks overlapped and trimmed, and its keys: copy with that part's keys, shown with its part's Shown keys, or none). pivot is what it turns about ([x, y, z], or a preset in the part's own terms, whichever way the view looks: centre, top, base, joint, front, back, its_left or its_right; a character faces +z, so its left is +x, the side on the S sprite's right; joint is where it touches its parent: the middle of that, or for a limb lying along it the end it hangs from, an arm hanging against a body at its shoulder, the top of where they meet; parent given before or in the same call; on a part with a twin the twin's pivot moves with it, mirrored, as in Model mode, unless twin_mirror: false, given only with pivot, and the answer's twin and twin_pivot say so) and parent what it moves with; keys ([{ frame, rotate?, move?, ease?: in_out | linear | hold | smooth | ease_in | ease_out }]) pose it on frames of an action's motion (the one on show, or action), which frames, frame_ms and loop set; the blocks, pivots and parents are every action's. A part's motion is six tracks (turn_x … move_z), each keyed on its own: keys sets them from whole poses, tracks ({ turn_y: [{ frame, value, ease? }], … }) sets only the ones it names. hold stays put, then jumps on the next key. Turns are degrees about x, then y, then z: +x rolls a wheel forward. A loop runs from the last key back to the first, so a wheel keyed 0 on frame 0 and 315 on frame 7 of 8 turns round and round; a track's one key holds on every frame. delete takes the part away: the parts that went with it go with what it went with (now_with; on their own if nothing), each where it stands, and its motion is baked into their keys on every whole frame of every action (baked), so they keep their pose; children names them. Twins and the mirror plane, each given on its own (with part): mirror_part: true is Model mode's Mirror part, the part's other side made across the model's x mirror plane and linked to it as its twin (its blocks and pivot mirrored, going with the twin of what it goes with, its name's side swapped, Arm L to Arm R, a name with no side taking R and the part L, and every action's keys mirrored: Turn X stays, Turn Y, Turn Z and Move X go the other way; the answer's made, from, renamed and plane say what it did, and a part with its other side already is refused: update_from updates it); twin names the part's twin (null or "" unlinks it; links either part had to another are let go, and the answer's unlinked names those parts); update_from puts the part back as that part mirrored, from its twin or the part its name's other side names only (update, given only with it: blocks, its blocks and pivot, the default, or blocks_and_keys, its rest and every action's keys too); pair_by_names: true, with no part, links every pair named for each other's side (Arm L and Arm R), as CHECK's Pair by names does; mirror_plane moves the plane square to axis (x, the default, y or z, given only with it) to box_middle, part_middle (of part) or a number of blocks within the box, to the half block, as the plane's tag in Model mode does (Agent: mirror plane at x 9.5; where it stands already, a note and no step). With the twin mirror on (the default), a build or a paint on one twin in Model mode, and model_shape, lands mirrored on the other. get_model names each part's twin and the plane, mirror_at ([x, y, z] in blocks: the box's middle until it is put elsewhere); its mirror is a part's own Mirror X, Y and Z, which model_part doesn't set. limits sets a part's joint limits, as the PART card's LIMITS does: free (none), or { x?, y?, z?, hinge? } over those it has, each Turn axis [low, high] degrees from its rest (low -180 to 0, high 0 to 180: the rest lies within it), locked (it stays at its rest) or free, and hinge x (it bends about X alone: Y and Z locked) or false (every lock off). Every key writer keeps to them from then on: model_pose, Model mode's rings (a ring stops at a limit, a locked one refuses), and this tool's keys and tracks (the answer's limited and note say when they were kept within them). chain make makes an IK chain of the part and the part it bends with (a forearm or a shin with what it goes with, else the part with the first part going with it: Model mode's Make a chain; one step, Agent: IK on Leg L), remove takes the chain it is in away (its keys stay). A chain goes by itself when either part is taken away or goes with something else (a delete, a merge, a re-parent or a hold): the answer's ik_removed and the pill say so (IK on Leg L removed: its shin now goes with Hips). get_model lists the chains and each limited part's limits. Shown keys, swaps and held things, each given alone (with part): shown { frame, on } shows or hides the part from that frame (from 0) of action on, Model mode's Shown row: a stepped track apart from its turns and moves, before its first key as the part rests (a blink is an Eyes shut part shown for one frame, as the character templates' Idle has it); on a part of a swap group, on: true shows it alone from there, the others hidden, as far as the group's next change (the POSE card's chips: Agent · Mouth: Smile from frame 6 to 8; the answer's to is the run's last frame), and on: false hides it only where none of the group shows (a socket's empty; a mouth always shows one of its parts). rest_shown says whether it shows as the model rests and on every frame no Shown key covers (the eye, visible, stays the editing hide, never keyed); a swap group's part rests as its one choice, the others hidden (false only for a socket's props), each keyed frame showing as it did. swap_with groups the part with the part named, shown one at a time (a mouth's Open, Shut and Smile; the one joining rests hidden while another rests shown, and a group it leaves for the other's, when it was that group's part resting shown, rests as its first), leave_swap: true takes it out (it rests as it did, the answer's rests_shown saying which; the group, when it was its part resting shown, rests as its first; after either, the answer's rests_shown_now names a part that came to rest shown so, as the pill does). A group that rested with none shown, as a blink's lids do, keeps resting so whichever part leaves it (deleted, merged, held or swapped away too): a lid never comes to rest shown by itself. socket makes a socket on the part (Model mode's + ▾ › Socket on): a control named {part} socket going with it, at [x, y, z] (a point of the model as it rests) or the middle of a side of its blocks (top, bottom, front, back, left, right: its left is +x); held_by puts the part in that socket's hand: it goes with the socket, its pivot at the socket and its grip kept, the hand's pose carrying it on every frame (props on one socket are a swap by themselves: Hand R: Sword · Torch · empty); export_point marks a control a point (a socket is made one): render_model keeps each point as a slice keyed on every frame it renders (its answer's points). get_model says each part's shown (at_rest and its keys as [frame, shown]), socket and point, the model's swaps and lamps_with. No two parts share a name, letters' case aside, and a part is found by its name either way.

  • model_pose { key? | reset? | mirror? | ik? | pose? | save?, part? | parts? | all?, frame, action?, reach?, keep_foot?, flip?, plant?, at?, amount?, mirrored?, mine?, to? } poses the model on one frame (from 0) of an action (the one on show unless named), one of six a call:

    • key six keys part, the parts named or all of them on all six tracks (Turn X, Y, Z and Move X, Y, Z), turns on their three turns alone, each at its value there, so the frame stands as it did and a key there already stays as it is: Model mode's K, Shift+K and the posing bar's Key ◆. A turn an older key (made before a joint limit) has past that limit there keys at the limit instead, so the frame changes there, and stopped says where (Shin L's Turn Y stops at 0°). A part with no blocks yet that is not a control is left out (skipped); a control, such as a character's Hips, is keyed like any part. The answer names the parts keyed and the tracks.
    • reset true puts part, parts or all back at rest there, each property they have keys on keyed at its rest value (the posing bar's and the POSE card's Reset).
    • mirror twin puts part's pose there on its twin, mirrored across the x plane (Turn X stays; Turn Y, Turn Z and Move X the other way), as the POSE card's Mirror to does; whole swaps every pair of twins on that frame and mirrors the parts with no twin where they are (a head turned left turns right). Each property that stands elsewhere is keyed there.
    • ik names a part of an IK chain (get_model's chains: an arm and its forearm, a leg and its shin), its upper or its lower, with one of: reach [x, y, z] puts the chain's end (its lower part's tip: a shin's sole under the knee) at that point in the model's blocks, both parts turned and keyed on the frame (the lower on its hinge's turn alone, Turn X for a knee), the bend kept as posed, within their joint limits; out of reach the limb straightens toward it (the answer's reach, the distance over the limb's length, and out_of_reach; a target too near for the bend to fold to is out_of_reach too, with off_by, the blocks the end stays off); at a joint limit the upper aims for the bend the limits keep, and stopped says where (Shin L stops at 90°); keep_foot: true keeps the lower part's first child (a foot) turned as it stood (with none, a note says it did nothing). flip: true bends it the other way, the frame re-posed with its end where it was (Flip bend); where the other way is past a joint limit (or its end would move) nothing is keyed and the chain keeps its way: changed and flipped false, stopped saying why (Shin L stops at -10° · it can't bend the other way). plant [from, to] holds its end where frame puts it (or at, [x, y, z]) on every frame of the range, each solved under the body's motion and keyed, so a foot stays put while the body walks on (the Plant pin; the answer's keys counts a part keyed on a frame once, missed the frames a joint limit or the reach kept its end off, with stopped; planted there already, nothing changes, and missed and stopped still say the frames held off).
    • pose names a pose of the pose library (Model mode's POSES under the POSE card) to key on part, parts or all (the default: every part): the model's own first (get_model's poses; a character template comes with Stand, Contact, Pass, Jump, Sit and Wave), else My poses (the app-wide library, by part name, so a pose there fits any character with parts so named; mine: true looks there alone). A pose holds each part's six values as the change from its rest, put on this part's rest, every turn the way round nearest where it stands and within its joint limits. amount (0 to 1, default 1) blends it in that far from where the parts stand (a drag on a thumbnail); mirrored: true puts each side's values on the other side, mirrored across x (Alt+click). The answer names the parts keyed and where the pose came from (model or mine).
    • save keeps the pose part, parts or all (the default) hold on the frame under that name, made unique: to model (the default) into the model's library, mine into My poses (the app's own, kept with its settings: no undo step).

    Each is one undo step in Model mode, named for what it did (Agent: key the pose of 9 parts, Agent: reset Arm L, Agent: reach with IK on Leg L, Agent: plant IK on Leg L, Agent: the pose Wave, Agent: blend in the pose Jump, Agent: save the pose Lean), none when the frame stands so already (changed: false and a note).

  • rig_model { do?, leave_out?, include?, joint?, joints?, rerig? } is Model mode's Rig it: the parts made a rig in one step, from the root out (a part named Hips, Pelvis, Body, Torso or Chest, in that order, else the biggest part, a guess). Each part goes with the part it touches most (one of the kind it hangs off first, a forearm its arm; what it meets at its end before what it lies along), turns about the joint where they meet (an arm hanging against a body about its shoulder, the top of where they meet), a Part N is named by where it sits (Head, Arm L, Leg R, Tail; Forearm L down an arm), and each joint is made overlap where they meet face to face, else flush. do preview (the default) lists the rows and changes nothing: each row's part, the name it gets, goes_with, pivot (null: as it is), joint, how they meets, guess, a warning where posing would open a gap, a note, changes_motion, ticked, blocked (it can't go with what its row says while that goes with it, a row upstream left out: apply leaves it as it is) and said. apply makes the ticked rows, but those in leave_out (by a part's name, as it is or as its row gives it), as one step, and chains each forearm with its arm and each shin with its leg for IK (get_model's chains), each elbow and knee so chained, where its turns were free, left to bend on the turn nearest its bend at rest, the other two locked: the joint limit hinge x for a knee or an arm hanging down, Y alone for an arm held straight out to the side; an arm held out at a slant (its bend 25° or more off every turn) keeps its turns free, and IK bends it about its own bend (the preview's chains_due counts them, the answer's chains_made those it made; over a rig, chaining limbs alone, with no row ticked, needs no rerig). A part with keys of its own that would go with a part that moves starts unticked (its motion would change) and keeps its pivot: include ticks it. joint sets every row's joint where Rig it can make it (overlap and rounded need them to meet face to face, the part turning about the joint; rounded an end of it facing what it goes with), the other rows keeping the one offered (kept_joint lists them); joints sets one row's ({ "Leg L": "rounded" }), refused, saying why, where it can't be made (and on the root's row). Over a model rigged already (a part goes with another), apply needs rerig: true.

  • model_action { do?, action?, name?, copy_of?, steps?, whole_pixels?, from?, offset?, stride?, bob?, arm_swing?, tail_sway?, frames?, breath?, sway?, replace?, sprite?, actions?, leave_out?, frame?, times?, ms?, timing?, span?, onto?, parts?, tracks?, ease? }: the model's actions, named motions such as Idle and Walk, sharing its parts and each with its own keys, frames, speed and loop, and its own steady pixels. do is list (the default), add (no keys, the frames and speed of the one on show, or copy_of another, keys and steps too; the one on show stays), rename, delete (a model keeps one), show (the one Model mode shows and edits, and the one the other tools use when told none; not an undo step) or set (an action's steps and whole pixels; action, else the one on show). steps is free or 8, 16 or 32 a turn: only the turn away from the rest is stepped, after easing, so each frame is a clean drawing; the keys keep their values and the glTF stays exact. whole_pixels lands the moves on whole pixels at the sprite's pixels per block, each part's pivot on the pixel grid. A new action is steady as Model mode makes one (16 steps a turn for a sprite up to 64 px, 32 above, and whole pixels) unless told otherwise; models from before and models built in code are free. list says each action's steps and whole_pixels. other_side is Make the other side: in action (else the one on show), each twin on one side (from: left, the default, or right) gives its keys to its twin, mirrored across the x plane, offset frames later round the loop (half, the default: a walk's second side in one call; none; or a number of frames, less than the action's); a part with no keys there gives nothing, and the answer's other_side lists the parts it changed. walk and idle are Model mode's A walk… and An idle…, for a rigged character (its legs found by name, else by its IK chains and twins; refused without two legs, saying so): walk takes stride, arm_swing and tail_sway (degrees) and bob (blocks), each landing on the action's Steps grid as the card's sliders do, and frames 6, 8 or 12; idle takes breath (blocks) and sway (degrees). Each makes a new action (name, default Walk or Idle, made unique), steady, and shows it; with replace: true it replaces the keys of action (else the one on show), its name and steps kept. The answer's made says the action, its frames, the parts keyed and the values as they landed. bring_in is Bring in actions from…: sprite names another open sprite (its tab's name) whose model's actions (default all) come in, each an action of its own, its name made unique, with its frames, speed, loop and steps; each of its keyed parts goes onto the part here of the same name, else onto the twin of where its own twin went (mirrored across x where it stands on the other side); leave_out names its parts to leave out; moves are scaled by the ratio of the legs' lengths, so a short fox kit takes a tall hare's walk, and the first action brought in is put on show (the answer's shown). The answer's brought lists the actions, each row and the scale. Timing (Model mode's frame menu, its action menu and the keys' grips; MODEL3D_PART6_PLAN.md Phase 37), each in action (else the one on show): hold holds frame (from 0) times frame lengths (1: one frame again), or the nearest whole number of them to ms; its rendered sprites last so, and the exports with them (Godot's per-frame duration, the JSON's, Unity's keys). timing is even (every frame one frame long) or attack (long · short · short · short · long · short spread over its frames, a long beat twice as long). insert_frame puts a frame in at frame (0 to the frames: their count adds one at the end) and delete_frame takes frame out (its keys go), every later key of every part's track, Shown's too, a frame later or earlier; the other actions are untouched. stretch stretches the keys from span's first frame to its last (of parts, default every part; of tracks, default the six) onto a span that keeps one of its ends, about that end, in whole frames (refused where two keys of a track would meet). ease sets how keys run on (of parts and tracks, within span; by default every key): smooth (the motion carried through each key, never overshooting), in_out, ease_in (slow out, speeding in), ease_out (at speed, slowing in), linear or hold; model_part's keys and tracks take the same words. Shortening an action keeps its late keys past its end (greyed in Model mode; lengthening it brings them back), and drop_kept lets them go. The answer's timing says what each did, and list says each action's holds ([frame, times]) and kept_keys where it has them. Names are up to 24 characters, no two alike.

  • model_light { azimuth?, elevation?, intensity?, colour?, ambient?, ambient_colour?, lamps?, lamp?, goes_with? }: the light a render bakes in. The sun is the document's (Lighting mode shows the same one), in the picture's terms: azimuth clockwise from the top of the sprite (315 is the upper left), elevation out of the picture towards the viewer (below 0: from behind). It stays put on screen as the model turns. lamps replace the model's lamps ({ at, colour?, strength?, reach?, shadows?, goes_with? }, at most 16); a lamp's goes_with names the part whose pose carries it from where it rests (a torch's flame with the torch: Model mode's lamp WITH). lamp (its place, from 0) with goes_with (a part, or null: on its own) sets one lamp's alone, one step (Agent: lamp goes with). With nothing given it tells the light as it is, each lamp's goes_with too.

  • model_reference { action?, plane?, image_path?, png_base64?, name?, offset?, scale?, opacity? }: the model's reference drawings, to build over (Model mode's Model › View › Reference…), one on each of the front, side and top planes. Each lies on the box's far side as its plane's view sees it (the front at z 0, the side at x 0 with its right toward −z, the top on the floor) and stands at first on the floor across the box's middle, one block a pixel, at 30%. It is never rendered: no sprite, export or check reads it, and the sprite's size never cuts it. action is list (the default), add (the image onto plane, in place of the one there: the answer says replaced), place (offset [right, up] in blocks from where it first stands, scale in blocks a pixel from 1/16 to 16, opacity 0.05 to 1) or remove; each change is one step (Agent: reference on Front), and every answer lists the drawings with each one's span on its plane.

  • model_colour { replace?, swap_to?, from?, glow?, shade?, part?, block?, face?, steps?, twin_mirror?, variant?, delete?, on? }: the model's colours across every part, as Model mode's COLOUR › IN THIS MODEL has them. Given nothing it reads them and writes nothing: colours (each one's hex, its faces in every part, hidden ones too, its parts and its glowing faces, the most used first), variants and the palette on show. One write a call, each one step: replace { "#from": "#to" } every face of each in every unlocked part, all at once, each block's glow kept (Agent: replace a colour; a locked part keeps its own, locked naming it); swap_to a palette's name, the model's colours mapped onto it slot for slot from the palette on show (from: another), the answer's pairs and the colours that stay; glow { "#colour": true } every face of it giving off its own light (unlit from every side, no darkened line, in a normal-map render's emission map), false taking the light again; shade lighter or darker on part's block face, steps 1 to 8, along its ramp in the palette on show as Paint's Shade steps it, landing mirrored on the part's twin too in the same step (twin_mirror: false keeps it on the part; the answer's twin and twin_changed; the ramp's end, and a face another block of the part covers, refused); and variant, one of OUTPUT's VARIANTS: { name, colours, swaps, shown, on } made or replaced by its name (swaps a swap group's pick by group, shown a part shown or hidden as the model rests), or a variant's name with delete: true or on. A variant renders the model otherwise (render_model's variants) onto a hidden layer of its own, Model · Arctic, and never changes it. part, block, face, steps and twin_mirror go with shade alone, from with swap_to, delete and on with a variant's name: given otherwise they are refused, never passed over. A glow's answer names the locked parts that keep their own.

  • scale_model { by }: the whole model twice as big (2) or half (0.5), one step (Agent: scale the model ×2): every part's blocks, pivots and rest moves, every action's Move keys (turns stay), sockets, lamps and their reach, the IK chains' tips, the mirror plane, the pose library's moves and the drawings, the box with them. ½ is refused where a part would lose blocks it can't halve (Arm L is 3 blocks thick: ½ would break it); it is exact where the blocks come in whole 2 × 2 × 2 cubes, as a ×2 leaves them. The answer gives the box (size), tall and blocks, and capped when something couldn't follow all the way and was held at its limit (a lamp's reach, 1 to 64 blocks; a drawing's scale, 1/16 to 16), the pill saying it too.

  • render_model { into?, action?, actions?, names?, anchor?, ground_row?, directions?, angle?, tilt?, pixels_per_block?, outline?, by_lighting?, normal_maps?, lines_at_joints?, keep_details?, rest_light?, block_dither?, left_out?, tilts?, framing?, canvas?, sprite_size?, variants? } turns the model into pixel art: every direction as frames with a tag each (every frame of the action's motion, at its own speed; Walk S, Walk SW... once there is more than one action), the last render updated in place, a turntable, the front view as a layer, or a new sprite. into is update (the last render's frames, tags and durations replaced on the same Model layer, its frames keeping their ids, a run's end growing or shrinking when its count changed, every other layer left as it is: fixes painted on a layer above Model stay; with nothing rendered yet, frames after the last), after (or frames, the default), new_layer (or layer), turntable or new_sprite. A fresh one-frame sprite with nothing drawn takes a render from its frame 1. actions (names, or "all") renders a character sheet, action by action in the model's order, each at its own speed; names reads the tags Walk S, walk_S or walk_down (a model with one action keeps the bare S, SW...; two tags of one name are refused). What isn't given is the model's own, as the user's Render takes it: its names, its extra tilts and the directions it leaves out (with its own directions; with another angle asked, those facing as one it leaves out did, as the camera saved keeps them, so the same call twice renders the same sheet), and on an update the actions it has ticked, and the pixels per block, light (baked in, with normal maps, or by Lighting) and outline the last render was made with (a render recorded before this build: the model's own), so an update with nothing else asked renders again the sheet the last render made (an update rendered without normal maps clears those on its frames); any other render not asking them is fitted to the sprite (pixels_per_block 0), baked in and outlined. A canvas not asked is the model's own as OUTPUT shows it (its smallest square only with its pixels per block set, which it then takes). actions goes with update, frames or new_sprite only (a turntable, a layer or a picture renders one action). Model mode, open on the sprite, stays open with the render behind it; the answer says the action (the one rendered; null for a sheet of actions: asked with actions, or an update rendering the actions OUTPUT has ticked), the actions, names and tags_made, and the frames it put in and took out (frames_added and frames_removed: an update can do both). It renders from the model's sprite camera: its angle style, tilt and directions (2-64), as Model mode's header shows them. Those given become the model's sprite camera, one undo step in Model mode (Agent: sprite camera), so the next Render there uses the same sprite camera (its other settings, pixels per block and the rest, are the user's own); the answer says the sprite_camera it used. More of OUTPUT can be set for the render alone (Lock to the palette, the outline's Outside or Inside and the line's own colour stay the user's Render's: an agent's render draws without them): left_out (directions by name, one at least kept), tilts (more tilts), framing (model, centred on its blocks, or box), canvas (sprite, or smallest_square with pixels per block 1 to 6) and sprite_size ([w, h] or "fit", the smallest that holds every direction as this render makes them, at its pixels per block, from its camera, tilts, framing, anchor and directions: the sprite resized round its middle first, or with anchor feet about the ground row, the frame's foot keeping its pixels and the row kept as the model's own, as Model mode's size card does, a step of its own, checked before anything changes); and variants renders OUTPUT's VARIANTS too, each onto a hidden layer of its own (Model · Arctic) over the same frames and tags, so the sprite and every flattened export show the model until its eye is opened (a new sprite: a sprite of its own each), an update replacing each on its layer, its eye as it was, and clearing on its frames the layer of one it no longer renders: true (the default) the model's ticked, false none, names of the model's, or variants given whole ({ name, colours }) for this render, two of one name refused. With a normal map, faces that glow come with an emission map too. The answer says the variants, left_out, tilts (those past the camera's own tilt it rendered: none from iso, each once), framing, canvas and sprite_size it rendered with. A layer, a turntable or a picture renders the camera's own tilt and leaves no direction out: tilts and left_out asked with one are refused, and its answer's tilts and left_out are empty. They keep the header's rules: a tilt names its style (0 side, 90 top, -90 bottom, anything else three_quarter), so side, top or bottom at a tilt not theirs is refused; iso has its own tilt and its 4 directions, so a tilt, or other directions, with it is refused. A refused render (an action the model hasn't got, a shared session) writes nothing, the sprite camera included. Steady pixels (Model mode's OUTPUT › MORE) are the model's own unless given for the render alone: lines_at_joints (false: between a part and the part it goes with a line needs the 1.5-block step it needs inside a part, so an elbow never flickers a seam line and an arm across the chest keeps its line), keep_details (a one-block painted detail that wins no pixel gets the pixel it covers most), rest_light (moving parts lit as they rest, so no face's shade pops mid-swing) and block_dither (the light's dither by the block a pixel shows, riding with the part). A character from model_character takes the cleaner look (no lines at joints, the other three on); models from before and models built in code render as they always did. The answer says the four it rendered with. anchor feet stands the floor point under the rest pose on one row and column of the sprite in every action, direction and tilt (the feet never hop), on ground_row (the sprite's row they stand on, 0 its top), and writes or updates the sprite's Origin slice with that point as its pivot, which the engine exports take as the sprite's origin; middle centres the model as before (a middle update, or frames, takes the Origin slice the last render wrote away). Left out, the model's own (a model_character anchors its feet). The answer says the anchor, the ground_row (where the feet stood, the Origin slice written or not) and the points it wrote: points.Origin ({ x, y }, where the feet stand) and each point ticked on OUTPUT's POINTS (a socket's, or a control's marked export_point) by its slice's name, [{ x, y }, ...] a sprite: a slice keyed on every frame it made (a point called Origin keeps Origin point), an update replacing the keys on its own frames and every render keeping the others' (a turntable writes none). points { name: true | false } sets POINTS for this render by the same names, Origin the anchor's slice (a point called Origin goes by Origin point), the rest the model's own ticks. export_model { path } writes it to an absolute path as .glb (parts, colours and each action as an animation named after it), .obj (with its .mtl and palette texture) or .vox. The answer says the actions the file carries and, for a model that anchors its feet, its origin (the floor point in blocks, kept in the .glb scene's extras) and origin_pixel (the sprite's Origin slice pivot). None of the three carries glow: a glowing face goes out in its colour, unlit, and the answer's note says so.

PixelAOI refuses changes while one of its dialogs or a filter is open, or while you are drawing; the error says which, and the call can be made again after. A change to the 3D model while the user holds a press waits for the let-go instead, up to 25 s, and calls sent after it wait behind it, in order.

Example

"Take ./hero.png, pixelate it, put it on the canvas, then bake a noise texture behind it with a Canvas blueprint."

The agent calls pixelate_image, then builds CanvasNoise → CanvasOutput with the Blueprint tools and runs blueprint_bake.

"Draw a little red car from the front, the side and the top, make it 3D, spin its wheels, and give me sprites from eight directions and a .glb."

The agent draws the three views as PNGs and calls model_carve, then model_part for each wheel (split_from the body with a cylinder along x, pivot centre, so it goes with the body cut flush, keys turning it about x), model_light for the sun, render_model for the frames and export_model for the .glb.

"Make me a hedgehog that walks, and give me its walk from eight directions."

The agent calls model_character with plan small, looks at it with look_model (direction all), then render_model with action Walk.

Config

  • PIXELAOI_BRIDGE_HOST (default 127.0.0.1)
  • PIXELAOI_BRIDGE_PORT (default 48653). PixelAOI reads the same variable when its link turns on, so to move the port, set it for both. On a moved port the token is in agent-bridge-token-<port>.
  • PIXELAOI_PROFILE: the editor's profile, if it runs under one; it says which folder holds the token.
  • PIXELAOI_BRIDGE_TOKEN: the token itself, in place of reading the file.

If it can't connect

The error says what is wrong and how to fix it:

  • can't reach PixelAOI or agent link isn't on: open PixelAOI and click agent off so it says agent ready. If it already says that and there is still no token file, the editor is older than the token handshake; update it. A PixelAOI running under PIXELAOI_PROFILE keeps its token in its profile's folder, so the server needs the same variable. A PixelAOI whose data folder the server cannot see (PixelAOI itself sandboxed, as a Flatpak or Snap app is) needs the token given to the server: set PIXELAOI_BRIDGE_TOKEN to the contents of its agent-bridge-token file.
  • the link to PixelAOI closed while working: another agent connected with the token and took over (one agent at a time), or the link was turned off. Calls PixelAOI had not started yet are dropped, not run. Run one agent with PixelAOI at a time.
  • agent: port busy (retrying) in PixelAOI's status bar: another PixelAOI, or another app, holds the port. PixelAOI tries it again every few seconds, so a port held for a moment frees itself. Otherwise close the other one, or move both to another port with PIXELAOI_BRIDGE_PORT (each port has its own token file).
  • refused the agent link for any other reason (an old token, say): try again; the server reads the token afresh for every connection.

If the editor closes, or the link is turned off, while the agent works, the next call reconnects once it is back. A call that times out may still be carried out by PixelAOI once it catches up (say, after a dialog closes), so the error asks the agent to look before running a change again.

As a Claude Desktop extension

manifest.json and icon.png describe it as a Desktop Extension (its name, icon, tools, and the editor's port as a setting: leave it at 48653 unless PixelAOI runs with PIXELAOI_BRIDGE_PORT). Build the .mcpb with npx @anthropic-ai/mcpb pack in this folder, then open it with Claude Desktop.

Get the editor at pixelaoi.pro.

Keywords