[ide-bridge]
Docs menu

Install

Get ide-bridge running on your machine in a few minutes.

Prerequisites

Before you start, make sure you have:

  • Node 22 or later. ide-bridge uses native fetch and async iterators that are not available in earlier runtimes.
  • pnpm 10+ or npm 10+. Either package manager works for the global install.
  • A supported agentic IDE. At least one of: Claude Code, Cursor, Kiro, or Antigravity. Any other MCP-capable IDE also works via the generic fallback.

Node 20 will not work

ide-bridge requires Node 22+. If you are on Node 20 you will see a runtime error on startup. Run node --version to confirm your version, then upgrade via nvm install 22 or the nodejs.org installer.

Install

ide-bridge is distributed as a global CLI package. Choose your package manager:

npm

npm install -g ide-bridge

pnpm

pnpm install -g ide-bridge

yarn

yarn global add ide-bridge

After install, confirm the binary is on your PATH:

ide-bridge --version

pnpm global bin not on PATH?

If ide-bridge is not found after a pnpm global install, run pnpm setup and then source ~/.zshrc (or your shell rc file) to add pnpm's global bin directory to PATH.

Start the daemon

Run the daemon in the foreground from any terminal:

ide-bridge start

Expected output:

ide-bridge listening on http://127.0.0.1:31415/mcp

The daemon binds exclusively to 127.0.0.1 (loopback only — zero network egress). It stays in the foreground. Press Ctrl+C to stop, or run ide-bridge stop from a second terminal.

Run as a service (optional)

To have ide-bridge start automatically when you log in, install it as a system service:

ide-bridge install-service

macOS (launchd) — writes a plist to ~/Library/LaunchAgents/com.ide-bridge.daemon.plist. Load it immediately without rebooting:

launchctl load ~/Library/LaunchAgents/com.ide-bridge.daemon.plist

Linux (systemd --user) — writes a unit file to ~/.config/systemd/user/ide-bridge.service. Enable and start:

systemctl --user enable --now ide-bridge.service

Once the service is running, launching ide-bridge start from a terminal will print "daemon already running" — that is expected behavior.

Verify

Check that the daemon is running and reachable:

ide-bridge status
# running pid=12345 port=31415

Then send a tools/list request to confirm all six tools are registered:

curl -s -X POST http://127.0.0.1:31415/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

You should see a response listing: save_checkpoint, load_checkpoint, append_decision, append_todo, list_projects, get_project_id.

All six tools listed?

You are ready to wire up an IDE. Head to the Quickstart for the full end-to-end walkthrough.

Uninstall

Remove the global binary:

# npm
npm uninstall -g ide-bridge

# pnpm
pnpm remove -g ide-bridge

Remove all stored checkpoints, config, and daemon logs:

rm -rf ~/.ide-bridge

If you installed the system service, also remove it:

# macOS
launchctl unload ~/Library/LaunchAgents/com.ide-bridge.daemon.plist
rm ~/Library/LaunchAgents/com.ide-bridge.daemon.plist

# Linux
systemctl --user disable --now ide-bridge.service
rm ~/.config/systemd/user/ide-bridge.service

Next: Quickstart →