Roam for Amp

Show local Amp coding activity on the map in Roam.

Install

Amp can install the plugin directly from its public TypeScript source:

amp plugins add https://raw.githubusercontent.com/WonderInventions/roam-amp-plugin/main/roam.ts --auto-update

The plugin is installed for all local workspaces. Reload plugins from Amp's command palette, or restart Amp, after installation. The --auto-update option lets Amp fetch new versions from the same URL.

Only install Amp plugins from sources you trust. Plugins execute code on your computer; roam.ts is the complete runtime source for this integration.

To uninstall it:

amp plugins remove roam.ts

How it works

The plugin listens for Amp's agent.start and agent.end events. While a local agent turn is active, it sends a small heartbeat to each locally running Roam release channel that has opted into the integration.

The plugin is inactive in Amp orbs and other remote executors. Roam must be running on the same computer as Amp.

Privacy

The requests reveal only:

• Whether an agent turn is active or stopping, including heartbeat timing
• A random, short-lived lease identifier generated independently for each agent turn
• The integration protocol version
• The installed plugin version

It does not send prompts, responses, Amp thread or message identifiers, tool calls, filenames, workspace names, or repository information to Roam.

Local development

Requirements:

• A recent version of Amp with plugin support
• Bun
• A local Electron build of Roam with the amp-on-the-map feature flag enabled

Install the development-only type dependencies and run the checks:

bun install
bun run check

To load the development source globally, link it into Amp's plugin directory:

mkdir -p ~/.config/amp/plugins
ln -s ~/code/roam-amp-plugin/roam.ts ~/.config/amp/plugins/roam.ts

Then reload plugins from Amp's command palette. Remove the symlink to uninstall the development plugin:

rm ~/.config/amp/plugins/roam.ts

Manual test

1. Run a local Electron build of Roam.
2. Enable Show Amp Activity on the Map in Roam's settings.
3. Reload the plugin in Amp.
4. Start an Amp turn and confirm that the Amp accessory and glow appear on your Roam office.
5. Finish or cancel the turn and confirm that the activity disappears.
6. Start overlapping turns and confirm that activity remains visible until the final turn finishes.

Distribution

Amp installs plugins from a single TypeScript source URL. roam.ts is therefore intentionally self-contained and has no runtime dependencies or build step.

If the implementation eventually benefits from multiple source modules or third-party runtime dependencies, the repository can add a small bundling step while continuing to publish one auditable TypeScript file.