Agentbridge

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.

1. Create the directory structure inside the shared folder:

   AgentBridge/

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

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

1. Launch AgentBridge on the Classic Mac. It will automatically find its folder and start polling for commands.

1. Send a test command from your modern computer:

   printf "BRIDGE 1.0.1\rSEQ 00001\rCMD ping\rTS 20260308T170000\r---\r" > /path/to/shared/AgentBridge-YourMacName/inbox/C00001.msg

1. Read the response:

   cat /path/to/shared/AgentBridge-YourMacName/outbox/R00001.msg | tr '\r' '\n'

You should see RESULT pong and STATUS ok.

Multiple Macs

Each Mac gets its own subfolder with its own copy of AgentBridge:

NAS Share/

└── AgentBridge/ ├── AgentBridge-SE30/ ← Mac SE/30 running System 7 │ ├── AgentBridge (app) │ ├── inbox/ │ ├── outbox/ │ └── assets/ ├── AgentBridge-G4/ ← Power Mac G4 running OS 9 │ ├── AgentBridge (app) │ ├── inbox/ │ ├── outbox/ │ └── assets/ └── AgentBridge-BasiliskII/ ← Emulator ├── AgentBridge (app) ├── inbox/ ├── outbox/ └── assets/

AgentBridge uses its own launch location as its working directory — no configuration needed.

MCP Server

The MCP server exposes AgentBridge commands as tools for AI agents like Claude. It's a Node.js TypeScript server that communicates via stdio (standard MCP transport).

Install via npm

npm install -g classic-mac-mcp

Or run directly with npx (no install needed):

npx -y classic-mac-mcp --config /path/to/fleet.json

Install from source

git clone https://github.com/SeanFDZ/agentbridge.git

cd agentbridge npm install npm run build

Configuration

Create a fleet.json file to point at your shared folders:

{

"fleet": [ { "id": "my-classic-mac", "alias": "Classic Mac", "arch": "68k", "os_version": "7.6.1", "shared_folder": "/Volumes/NASShare/AgentBridge/AgentBridge-MyMac" } ] }

Claude Desktop

Add to