AgentBridge

Let AI talk to your Classic Mac.

AgentBridge is a native Classic Mac OS application that lets AI agents (like Claude) interact with Mac OS 7–9 through structured commands and responses. It works on real hardware and emulators — no modifications to your Mac required.

Drop AgentBridge into a shared folder, launch it on your Mac, and an AI agent can list windows, open apps, type text, read the clipboard, browse files, and more — all through a simple text-based protocol.

How It Works

┌──────────────────────┐
│    Claude / AI Agent │
│         │            │
│    MCP Protocol      │
│         │            │
│    MCP Server (Node) │
│         │            │
│    Shared Folder I/O │
└────────┬─────────────┘
         │  reads/writes text files
         │
    ┌────┴──────────────────────────┐
    │  Shared Volume (NAS / AFP /   │
    │  SMB / emulator extfs)        │
    │                               │
    │  AgentBridge-MyMac/           │
    │  ├── inbox/   ← commands in   │
    │  ├── outbox/  ← responses out │
    │  ├── assets/  ← file staging  │
    │  └── heartbeat                │
    └────┬──────────────────────────┘
         │
┌────────┴─────────────────────────┐
│  Classic Mac OS 7 / 8 / 9        │
│                                  │
│  AgentBridge.app                 │
│  - Polls inbox for commands      │
│  - Executes via Mac Toolbox      │
│  - Writes responses to outbox    │
│  - Heartbeat every 2 seconds     │
└──────────────────────────────────┘

The transport is just a folder. How that folder is shared between the AI and the Mac is up to you:

• NAS/file server (AFP or SMB) — multiple Macs and your modern computer all mount the same share
• Emulator shared folder — BasiliskII and SheepShaver both support host directory sharing
• Any other shared filesystem — if both sides can read and write files, it works

No SSH. No special drivers. No modifications to your Mac's system. AgentBridge is a regular application — launch it, quit it, done.

MCP Tools Reference

The MCP server exposes these tools to AI agents. If the fleet has only one target, the target parameter is optional on all tools.

System & Status

classic_mac_list_targets List all configured Classic Mac targets and their status (heartbeat alive/dead). No parameters.

classic_mac_ping Health check — returns pong if AgentBridge is responding.

classic_mac_heartbeat Read the heartbeat file — shows uptime, front app, free memory, timestamp.

classic_mac_get_about System information — OS version, machine type, RAM, free memory, uptime.

Windows & Processes

classic_mac_list_windows Enumerate all visible windows across all applications. Returns window index, title, bounds (left,top,right,bottom), and front/back layer.

classic_mac_get_front_window Get details about the frontmost window — title, bounds, owning app.

classic_mac_list_processes List running applications with name, creator code, PID, and memory partition.

Menus

classic_mac_list_menus List the menu bar entries for the frontmost application.

classic_mac_get_menu_items Get items within a specific menu by name.

classic_mac_menu_select Activate a menu item by name. Works for items with keyboard shortcuts.

Mouse & Keyboard

classic_mac_click Click at screen coordinates.

classic_mac_mouse_move Move the cursor without clicking.

classic_mac_mouse_drag Click and drag from one point to another.

classic_mac_type_text Type a string of text into the frontmost application.

classic_mac_key_press Press a single key with optional modifiers.

Clipboard

classic_mac_get_clipboard Read the current clipboard text contents.

classic_mac_set_clipboard Set the clipboard text contents.

Application Control

classic_mac_launch_app Launch an application by HFS path or creator code.

*One of path or creator is required.

classic_mac_activate_app Bring a running application to the front.

classic_mac_quit_app Send a quit Apple Event to a running application.

classic_mac_send_appleevent Send a generic Apple Event to a running application.

Files & Volumes

classic_mac_get_volumes List all mounted volumes with name, free space, and total size.

classic_mac_list_folder List contents of a folder by HFS path. Returns name, type code, creator code, size, and whether each item is a folder.

Compatibility

AgentBridge requires System 7.0 or later (for Apple Events support).

Quick Start

Pre-built Binaries

Download from the Releases page:

• AgentBridge-68k.bin — MacBinary for 68k Macs (System 7–8.1)
• AgentBridge-68k.dsk — HFS disk image for 68k Macs (System 7–8.1)
• AgentBridge-ppc.bin — MacBinary for PowerPC Macs (OS 8.5–9.2.2)
• AgentBridge-ppc.dsk — HFS disk image for PowerPC Macs (OS 8.5–9.2.2)

Setup

1. Create a shared folder accessible to both your Mac and your modern computer. This can be a NAS share, an emulator's host directory, or any shared filesystem.

2. Create the directory structure inside the shared folder:

   Code

   Copy

   AgentBridge/
   └── AgentBridge-YourMacName/
       ├── inbox/
       ├── outbox/
       └── assets/
   

3. Copy AgentBridge into the folder alongside inbox/outbox/assets.