Read this BEFORE creating or editing any Scratch project.

Covers Scratch's hard limits (block counts, asset sizes, clone caps, cloud variable rules and so on) and the goboscript language used to write projects as text. Scratch projects are not edited as raw project.json here; they are written as goboscript .gs source and compiled.

Report whether the goboscript toolchain is installed and usable.

Call this first if any other project_* tool complains about a missing binary. Never raises, so it is safe to use for diagnosis.

Create a new goboscript project and make it the active project.

Scaffolds a project directory with stage.gs, main.gs, a blank costume and a goboscript.toml.

Register an existing goboscript project directory and make it active.

Decompile a Scratch project into editable goboscript source, and make it active.

Give either project_id to pull straight from scratch.mit.edu, or sb3_path for a local .sb3 file. Decompiling is lossy in layout terms: the result is equivalent code, not a byte-identical copy of the original.

List the goboscript projects this server knows about.

Choose which open project the other project_* tools act on.

Forget a project. Does not delete anything from disk.

Summarise a project: its sprites, publish target and compatibility.

Compile the project to .sb3 with goboscript. Use this rather than running the goboscript CLI yourself.

A failed build raises with the compiler's diagnostics passed through verbatim -- file, line, column and the offending source -- so fix those and call it again.

Also reports which extensions the project uses and whether any of them are TurboWarp-only, which would block publishing to scratch.mit.edu.

Build the project and upload it to scratch.mit.edu as the active session.

Creates a new Scratch project the first time, then reuses that id for later saves. Uploads costume and sound files as well as the code, since Scratch stores assets separately and the project would render broken without them.

Refuses to upload a project using TurboWarp-only extensions, and names them, because scratch.mit.edu will not accept it.

List the costumes and sounds a sprite declares.

Add a costume to a sprite, copying the file into the project's assets/.

Give either file (an existing .svg/.png/.jpg) or svg (SVG markup as a string, which needs name). Appended last, so it becomes the sprite's highest costume number.

Add a sound to a sprite, copying the file into the project's assets/.

Scratch accepts only MP3 and WAV; other formats make the project refuse to load, with no warning.

Remove a costume or sound declaration from a sprite.

Leaves the file in assets/ in case other sprites use it.

Inspect what a project actually compiled to.

Reads the built .sb3 and reports every target with its block and script counts, costumes, sounds, variables and lists, plus the assets embedded and which sprites use them. Use it to verify a build did what you intended -- that a costume really got attached, that layer order is right, that a sound is present and not oversized.

Requires a build; run project_build first. Warns if the source has been edited since the .sb3 was written.

Read the goboscript language documentation.

Call with no arguments to get the index of every documentation page. Call with page set to one of those paths to get that page as raw markdown.

Use this whenever you are unsure of a block or reporter name -- goboscript names differ from the Scratch block text (for example switch_costume, change_x, touching("sprite"), clone, set_ghost_effect) and guessing wastes a build cycle.

Set the thumbnail of a published project.

Scratch generates thumbnails in its editor, so a project uploaded through this server keeps the grey placeholder until one is set. project_save_to_cloud does this automatically; use this tool to change it afterwards.

With no file, the Stage's first backdrop from the latest build is used, converted from SVG if a rasteriser is available. 480x360 suits Scratch best.

Login to the Scratch site using set login details.

You may either provide a path_to_env, a scratch_username and scratch_password, or a scratch_session_id, or a browser_name (optional).

If none is provided, it will fallback to logging in via the user's installed browser.

Sessions are remembered across restarts by default, so this usually only needs to be called once per account. Check social_list_sessions first.

List the Scratch sessions this server currently holds.

Use it to discover what is already available before asking the user for credentials.

Choose which logged-in account subsequent authenticated tools act as.

Drop a session from this server and from the on-disk store.

Check with Scratch whether a stored session id is still valid.

Restored sessions are rebuilt offline from the session id, so an expired or revoked login looks fine until it is used. This performs a real request to confirm, and refreshes the account details on success.

Set the 'About me' section on the active session's profile.

Set the "What I'm working on" section on the active session's profile.

Fetch a Scratch user's profile.

Fetch a Scratch project's metadata.

Page through the comments on a project, a studio, or a user's profile.

The sources paginate differently because Scratch exposes them differently, so read the argument notes:

• source="project" / "studio": uses limit + offset. Replies are a separate request, so include_replies costs one extra request per comment.

• source="profile": uses page (30 top-level comments per page); offset is ignored. Replies always come back, free of charge, so include_replies is irrelevant here.

Only top-level comments are listed. Scratch has a single level of nesting: a reply to a reply is stored as a reply to the top-level comment.

Both sources page over a live feed, so on a busy project or profile a comment can shift between pages while you read them.

Fetch the replies to one top-level comment.

For source="profile" this is slow: Scratch has no endpoint for a single profile comment, so scratchattach pages through the profile until it finds the id. Prefer social_get_comments, which returns profile replies inline.

Post a comment on a project, a studio, or a user's profile, as the active session.

Requires a logged-in session. To reply to an existing comment, prefer social_reply_to_comment.

Scratch rate-limits commenting and rejects content it considers spam or disallowed, which surfaces as a CommentPostFailure.

Reply to an existing comment on a project, studio or profile, as the active session.

parent_id must be a TOP-LEVEL comment id. Scratch supports only one level of nesting, so replying to a reply must target that reply's top-level parent; social_get_comments reports is_top_level and parent_id for every comment so you can pick the right id.

Set the profile picture of the active session's account.

Scratch caps avatars at 500x500 pixels. An oversized image is rejected with HTTP 200 and an error in the body, so this checks the size before uploading and reads the response rather than assuming success.

SVG is not accepted by Scratch; rasterise it first (for example inkscape logo.svg -w 500 -h 500 -o logo.png).

Check the active account's message inbox.

Scratch splits the inbox across three endpoints with independent unread state, and this reports all of them:

• unread_count + messages: ordinary activity (comments, follows, loves). The count is genuinely unread, but the list is simply the newest messages whether read or not, so the two do not necessarily correspond.

• scratch_team_messages: alerts from the Scratch Team.

• invitation: a pending "become a Scratcher" invite, carrying its own unread flag.

unread_elsewhere is true when something is unread outside the activity feed, so an unread_count of 0 does not by itself mean an empty inbox.

Follow, unfollow, or check whether the active account follows a user.

Love and/or favourite a project, remove either, or just check.

"like" is Scratch's love (the heart); "favourite" is the star. They are independent, so both and removeboth operate on each.

Add a project to a studio as the active account.

Scratch only allows this if the account may add to that studio: it must be the owner, a curator, or the studio must allow anyone to add.

Search Scratch's shared projects, or browse them when no query is given.

Results are a lean summary: id, title, author, url, thumbnail and stats. Follow up with social_get_project_info for the full record of one project, or project_download to pull one apart and edit it.

Note: as of 27/07/26, the API is broken right now, so if it doesn't work it's an upstream issue -- not our one. You can, if you wish, search the web for status updates as to Scratch search functionality.

Accept a "become a Scratcher" invitation for the active account.

Scratch promotes a New Scratcher only after the Scratch Team invites them. On the website the invitation is accepted by reading through the Community Guidelines and clicking to agree, so accepting here means the account holder accepts those guidelines. For that reason nothing happens unless confirm is set: called without it, this only reports eligibility.

The guidelines are at https://scratch.mit.edu/community_guidelines and ask everyone on Scratch, in summary, to: be respectful, remembering the audience is broad and includes children; be constructive when commenting; share freely and give credit when remixing; keep personal information private; be honest rather than impersonating others or spreading rumours; and report anything inappropriate rather than escalating it.

Promotion cannot be undone.

Unpack an .sb3 into a diffable directory (project.json + assets/).

Pack a diffable directory back into an .sb3.

Summarise an unpacked project dir: targets, block counts, assets.

Fetch a Scratch studio's title, description, and stats.

List remix lineage info for a project (id, title, author).

List a user's favorited projects (id + title).

Read current cloud variable values for a project.

Set a cloud variable value.

Recent cloud activity log for a project.

Load an .sb3 file into the Node editor. (proxied)

Write the open project back to .sb3, live-reloading TurboWarp. (proxied)

Targets, extensions, monitors, meta of open project. (proxied)

Log in to scratch.mit.edu for the Node session. (proxied)

Download a scratch.mit.edu project by id for editing. (proxied)

Save the open project back to scratch.mit.edu (confirm-gated). (proxied)

Publish the project so it is public (confirm-gated). (proxied)

Every sprite with position/size/media. (proxied)

Full details for a sprite or Stage. (proxied)

Raw project.json entry for a target, or subtree at a JSON Pointer. (proxied)

Catalog of standard opcodes from scratch-vm, optionally by category. (proxied)

Full schema for one opcode incl. shadow encodings. (proxied)

Register an extension so its blocks load. (proxied)

Apply RFC 6902 JSON Patch (as JSON string) to a target. (proxied)

Set sprite props; props is a JSON object string (x, y, size, ...). (proxied)

Add a sprite; props is a JSON object string. (proxied)

Remove a sprite. (proxied)

Rename a sprite/stage target. (proxied)

Set stage props; props is a JSON object string. (proxied)

Set/create a variable on a target. (proxied)

Delete a variable. (proxied)

Set/create a list on a target; items is a JSON array string. (proxied)

Delete a list. (proxied)

Add a broadcast message. (proxied)

List sprite comments. (proxied)

Add a sprite comment. (proxied)

Edit a sprite comment. (proxied)

Remove a sprite comment. (proxied)

Add a costume from a file. (proxied)

Remove a costume. (proxied)

Add a sound from a file. (proxied)

Remove a sound. (proxied)

Load an .sb3 from disk in TurboWarp Desktop via bridge. (proxied)

Green flag in TurboWarp Desktop via bridge. (proxied)

Stop in TurboWarp Desktop via bridge. (proxied)

Load the open project into the headless VM. (proxied)

Press green flag in the headless VM. (proxied)

Advance the headless VM; returns state + event timeline. (proxied)

Budgets (seconds/frames) are omitted when 0 so the sidecar's own defaults apply (its zod schema rejects an explicit 0), and untilIdle / paced are only forwarded when set (None = sidecar default). paced=False runs the budget back-to-back with no per-frame sleep, which is what deterministic step-debug wants.

Stop all scripts in the headless VM. (proxied)

Snapshot headless VM state. (proxied)

Feed keyboard/mouse/answer input to the headless VM. (proxied)

keys accepts a JSON array of {key, isDown?} objects or a single key name (wrapped to a full tap). Anything else that parses to a non-list raises ValueError before touching the sidecar — the sidecar's zod schema would reject it anyway, but failing here gives the shorter, proxy-attributed error.

Live thread inspector: target, clone flag, hat, stack, status. (proxied)

Full monitor table (visible or not): label, opcode, value, mode. (proxied)

Step exactly one frame; returns before/after + delta. (proxied)

Deterministic PRNG seed for operator_random; None restores Math.random. (proxied)

Poll-and-diff variable watcher: old/new/changed per key. (proxied)

Recorded pen/sound stub calls since load. (proxied)

Pen raster as PNG base64 + non-transparent pixel count. (proxied)

Offline sound mix as WAV base64 + event count + seconds. (proxied)

Run the headless VM on virtual time until a predicate fires. (proxied)

until is a JSON object string, e.g. {"broadcastSeen": ["GameStart"]}, {"varEquals": [{"name": "Score", "value": 100}]}, {"threadsIdle": true} — fires when ANY entry matches (OR). Budgets omitted when 0 so sidecar defaults apply. Replaces N× sb3_vm_run poll loops with one call.

Set live VM state (fault injection mid-wave). (proxied)

Each arg is a JSON array string: variables entries {target?, name, value}, lists entries {target?, name, items}, sprites entries {target, x?, y?, direction?, size?, visible?, costume?}. Unknown target/variable/list/costume is an error.

Live clone census: name, pose, costume, sprite-locals per clone. (proxied)

Query every target's blocks map in the open project. (proxied)

Filters combine (AND): opcode substring, field value, input name, topLevel-only. Needs an open project, not the VM.

Validate target blocks against the opcode catalog. (proxied)

Omit target for all targets. Advisory — custom extension blocks ignored.

Capture the live TurboWarp stage as PNG (base64-wrapped note). (proxied)

Capture the live stage as compressed JPEG. (proxied)

Open (or create) a ScratchPy .spy project file; all other spy_* tools act on it.

What is in the .spy project: tabs, variables, lists, custom blocks, package packs.

Readable outline of every script in a tab.

The Python a tab's blocks generate.

THE MAIN BUILD TOOL: give ordinary Python, it becomes Scratch blocks in a tab.

Turn an existing .py file on disk into blocks.

Remove a tab from the project.

Create a variable or list, or change its starting value.

Run a tab's generated Python and return what it printed.

Every kind of block ScratchPy knows, with the Python each one produces.

Python packages installed in the environment ScratchPy uses.

pip install a package and turn it into blocks.

Make blocks for an already-installed module (stdlib modules work too).

Take a package's blocks back out of the project.