How AppleBridge Uses Apple Events: A Beginner's Guide with Examples

Apple Events are the classic Macintosh’s way of letting one program send a structured message to another and get a reply back. AppleBridge leans on exactly this mechanism for one specific job: running commands on the emulated Mac and capturing their output. This guide explains how that works, why it matters, and how to try it yourself — starting gently and building up.

The one-paragraph mental model

When you ask Claude (or type a raw command into the bridge) to run something like Echo 'Hello' on the Mac, the request travels from the host into the guest over TCP. Inside the guest, the AppleBridge daemon does not run the command itself. It packages the command as an Apple Event and hands it to a separate program — ToolServer — that knows how to execute MPW commands. ToolServer runs it, then sends the results back to the daemon inside the Apple Event’s reply. The daemon streams that reply out to the host. That round trip — event out, reply back — is the whole idea.

flowchart LR
    H["Host
(Claude / shell)"] -->|"TCP :9000"| D["AppleBridge Daemon
(on the Mac)"]
    D -->|"Apple Event
'misc'/'dosc'"| TS["ToolServer"]
    TS -->|"AE reply:
STDOUT, STDERR, STATUS"| D
    D -->|"TCP response"| H

Which Apple Event, exactly

AppleBridge sends a single, well-known Apple Event:

• Event class: misc
• Event ID: dosc (short for “do script”)

The misc/dosc pair is the standard “Do Script” event that MPW and ToolServer have understood for decades. The direct object of the event is the command text you want to run. When ToolServer finishes, it fills the reply with three things AppleBridge cares about: the standard output, the standard error, and a status (result) code. AppleBridge unpacks those and turns them into the {success, output} result you eventually see.

Think of misc/dosc as a four-letter “verb” and the command string as its “object” — the same shape as an AppleScript do script "...".

Why ToolServer and not the MPW Shell

This is the single most useful thing to understand as a beginner, because it explains a class of “it ran but I got nothing back” confusion.

Both ToolServer and the MPW Shell can receive the misc/dosc event. The difference is what they do with the reply:

So if you target the MPW Shell, the command genuinely runs, but the reply comes back empty and the output is left sitting in a window inside the emulator where the bridge cannot see it. AppleBridge treats the MPW Shell only as a fallback. For anything where you want the output — which is almost always — use ToolServer. That is why ToolServer is the helper app the setup guide tells you to add.

Where to get ToolServer: ToolServer isn’t a separate download — it ships as part of MPW (Macintosh Programmer’s Workshop). If you already have MPW on the guest, you already have ToolServer; you just point AppleBridge at it as a helper app. And MPW itself is available from the usual places you’d look for classic Mac development tools — the Macintosh Garden and the other well-known abandonware/retro-Mac archives all carry it.

A first example: Echo

Here is the simplest possible round trip. In a Claude Code session you would just say it in words:

You: Run Echo 'Hello from System 7' on the Mac
Claude: [calls the mpw_execute tool]
Result: Hello from System 7

Behind that single sentence, the bridge:

1. Sends the command text Echo 'Hello from System 7' to the guest over TCP.
2. The daemon wraps it in a misc/dosc Apple Event aimed at ToolServer.
3. ToolServer runs Echo, captures the output, and returns it in the reply.
4. The daemon sends back STATUS:0 and the captured text.

A STATUS of 0 means success — the same convention as a Unix exit code.

Trying it without Claude

You do not need the AI layer to see the Apple Event mechanism at work. The bridge exposes a plain control port on the host (:9001), so you can poke it with nc:

printf 'MACSTATUS\n\n' | nc -w 5 localhost 9001

If you see host_connected=1 and daemon_responding=1, the bridge is live and the Apple Event path to ToolServer is ready. From there, the MCP tool mpw_execute is the front door to the misc/dosc event — every command you run through it becomes one Do Script event and one reply.

A second example: Directory

Directory is MPW’s “where am I” command — a good test because it returns real text, not just what you fed in:

You: Run the Directory command on the Mac
Claude: [mpw_execute "Directory"]
Result: MeinMac:MPW:AppleBridge:

Same path as before: one misc/dosc event to ToolServer, one reply carrying the folder path as STDOUT. If you ever run Directory and get an empty reply, that is the classic sign your command reached the MPW Shell instead of ToolServer — the tell-tale symptom of the table above.

ToolServer is just one AE-scriptable app

Here is the part worth internalising once the basics click: there is nothing special about ToolServer as an Apple Event target. It happens to be the tool wired up today, but the misc/dosc channel is generic. The command travels as a “Do Script” event to an application, and any application that supports Apple Events can, in principle, sit at the other end.

That matters because plenty of classic Mac development tools are themselves scriptable. THINK C / Symantec C++ is a good example: its project manager (creator 'KAHL') exposes an Apple Event dictionary, so it can be driven exactly the way ToolServer is — open a project, ask for a build, and read the error list back from the reply:

tell application "THINK Project Manager"
    open "MeinMac:Dev:Hello:Hello.π"   -- the project file
    build current project              -- compile changed sources, then link
    set theErrors to errors of current project
    if (count of theErrors) is 0 then
        return "OK"
    else
        return theErrors               -- harvested over Apple Events, like ToolServer's reply
    end if
end tell

Notice the shape is identical to the ToolServer round trip: one event out, one reply back carrying the result. CodeWarrior (Metrowerks) is another candidate, with an even richer AppleScript dictionary for building and structured error reporting.

So the honest way to state AppleBridge’s Apple Event support is: the mechanism is not tied to ToolServer. It is a general Do-Script-and-harvest-the-reply channel, and ToolServer is simply the first, best-tested application plugged into it. Driving other AE-scriptable apps (THINK C, CodeWarrior) is documented as a design direction rather than a shipping feature today — but it is the same channel, not a new one. If you understand the ToolServer example, you already understand how any of them would work.

Where Apple Events stop

It is just as important to know what does not go over Apple Events, so you have the right mental map:

• File transfer, screenshots, input injection, directory listings, clipboard, launch and shutdown do not use misc/dosc. They are handled directly by the daemon over the TCP protocol.
• Driving another application’s menus uses a completely different technique — a global trap patch and a journaling driver — precisely because many classic apps expose no Apple Event interface at all.

In other words, Apple Events in AppleBridge are the command-execution tier: writing, compiling, linking, and running code through MPW/ToolServer. That tier is optional. If you never install ToolServer, the bridge still does screenshots, file transfer and input — you simply do not have the misc/dosc command path. An absent ToolServer is a tier you do not have, not a broken install.

Quick troubleshooting

• Command runs but reply is empty → you hit the MPW Shell, not ToolServer. Add ToolServer as a helper app and retry.
• mpw_execute errors with no connection → check MACSTATUS; if host_connected=0, the daemon has not dialled in yet (it retries every 30 seconds).
• Non-zero STATUS → the command reached ToolServer fine; the command itself failed. Read STDERR in the reply for the reason.

Result check

You have understood AppleBridge’s Apple Event support when you can answer three things: the event is misc/dosc (“do script”); the output comes back in the event’s reply as STDOUT/STDERR/STATUS; and ToolServer returns that reply while the MPW Shell does not. Run Echo and then Directory through the bridge and watch both come back with STATUS:0 — that is the full round trip, twice.