RoamCode

Self-hosted mission control for Claude Code and Codex.

Run the real coding-agent TUI on your own machine. Keep Sessions alive, step in from any browser, and turn repeatable work into Automations — without replacing the CLI you already trust.

Website · Get started · Documentation · Discussions

Start in three steps

RoamCode installs as a per-user service. It defaults to 127.0.0.1, keeps its own data locally, and prints a five-minute, one-use pairing link when installation finishes.

1. Install on the machine that runs your agents

macOS with Homebrew (recommended; installs Node.js and tmux dependencies):

brew install burakgon/roamcode/roamcode && roamcode install

macOS or Linux with Node.js 24+ and tmux already installed:

curl -fsSL https://roamcode.ai/install | bash

Prefer to inspect the bootstrap first? Read scripts/install.sh, then run the published CLI directly:

npx --yes --allow-scripts=better-sqlite3,node-pty roamcode@latest install

2. Open the pairing link

The installer verifies that the service is healthy, then prints a QR code and one-use link. Open it in a browser on the same machine. For a phone or another computer, first create a private or HTTPS route you control, then run:

roamcode pair --url https://your-roamcode.example

3. Open a terminal

Pick a working directory and choose Open terminal. RoamCode starts an ordinary login shell inside tmux; run claude, codex, or any other command yourself. When a supported coding agent becomes the foreground process, RoamCode detects it and adds its identity and status to the Session without changing the command, shell, or agent.

A Session only needs a shell. Install and authenticate a provider CLI when you want to run that agent. See the complete getting-started guide, including Linux prerequisites, remote access, and recovery.

One control loop

RoamCode is not a chat wrapper and it is not a hosted IDE. It is the control layer around the agent processes already running on your machine.

Surface	What it owns
Sessions	Persistent user-controlled terminals with detected agent status, files, split panes, and intervention.
Automations	Repeatable instructions with manual, schedule, and webhook triggers. Every Run becomes an inspectable Session.
Agents	Installed runtimes, authentication, availability, versions, capabilities, and active work on this Node.

The terminal stays the terminal

RoamCode streams the actual terminal through Ghostty Web. You start the provider in the shell, so its permission prompts, slash commands, diffs, model controls, subagent panels, sandbox settings, approval policies, and native safety behavior remain intact.

• Sessions persist in tmux and reconnect after browser or network changes.
• Desktop supports resizable, draggable, persistent split panes.
• Mobile adds a Termux-style key bar, sticky Ctrl, one-finger scrollback, selection, clipboard, and file exchange.
• “Needs input” status and Web Push take you directly back to the Session that is waiting.
• Stable updates are integrity-pinned, boot-smoked before activation, and retain the previous verified release for rollback.

Step into the live TUI Respond to the exact prompt or permission in place.	Select, copy, and chord Use selection, clipboard controls, sticky Ctrl, arrows, Esc, and paging.
Move the artifacts Upload inputs and download files produced by the Session.	Start the next Session Choose a Git-aware working directory without returning to a desk.

Local-first by construction

browser / installed PWA
          │
          │  device credential + network path you choose
          ▼
your RoamCode Node
          ├── persistent tmux shell Sessions
          ├── local Automations
          └── optional installed claude / codex CLIs

There is no RoamCode account, managed relay, or hosted control plane. Your repositories, provider credentials, prompts, terminal output, and execution stay on the Node. Provider CLIs continue to use their normal provider services. Remote access can use a private network, VPN, SSH forwarding, or an HTTPS reverse proxy you operate.

RoamCode is intentionally remote code execution on your own machine. Treat every paired browser like an SSH key and never expose the plain HTTP port to the public internet. Read the security boundary before enabling remote access.

Documentation

Guide	Use it for
Getting started	Install, pair, launch the first Session, and verify the service.
Terminal Sessions	Shell-first lifecycle, foreground agent detection, and optional integrations.
Remote access	Connect another device without exposing an unsafe public port.
Configuration	Environment variables, service behavior, API automation, and data paths.
Troubleshooting	Diagnose service, provider, terminal, pairing, and update failures.
Windows through WSL2	Run the Linux service and reach it safely from Windows.
Peer federation	Connect independent Nodes directly with explicit scopes.
Release model	Stable SemVer, npm, Homebrew, and OTA guarantees.

The additive product API is published by every Node at GET /api/v1/openapi.json.

Development

git clone https://github.com/burakgon/roamcode.git
cd roamcode
corepack enable
pnpm install
pnpm build

Use an isolated ROAMCODE_DATA_DIR, tmux socket, and PORT=0 for development or tests. Do not point a development process at an installed service's data directory or port. See CONTRIBUTING.md for the complete workflow and quality bar.

Community

• Ask questions and show what you are building in Discussions.
• Report reproducible bugs with the issue templates.
• Propose focused improvements through pull requests after reading CONTRIBUTING.md.
• Report vulnerabilities privately through GitHub; never open a public security issue. See SECURITY.md.

RoamCode is MIT licensed. See LICENSE.