Isomux - Give your agents a cute office

Feature Highlights

free · open source · no cloud · no account

Works with your Claude or ChatGPT subscriptions: if claude or codex works in your terminal, isomux works in your browser
Multi-provider: mix Claude agents and Codex agents in the same office
Works locally (run the server on localhost:4000, access it through your browser) or as a self-hosted persistent server:
- Run at home, access from any device and by anyone in your VPN (we use Tailscale)
- No syncing headaches: same conversations, same filesystem, every device updates in real time
- Conversation-level collaboration: anyone on your VPN can chime in
Visual office metaphor: see what every agent is doing at a glance
- Animated characters: sleeping when idle, typing when working, waving when waiting for you
- Skeuomorphic touches: click the moon to toggle dark mode, click doors to switch rooms, etc.
- Auto-generated topic below each nametag, so you remember what each agent is working on
Mobile UI: continue conversations on your phone with a touch-optimized UI
Agents can check on each other and message each other: all messages (human and agent) get queued while agents are busy.
Built-in terminal, editor, and diff tool
Voice-to-text prompting and text-to-speech responses
Custom commands in addition to your own: /isomux-peer-review, /isomux-all-hands, etc. (see /help)
Hierarchical system prompts: office-wide, per-room, and per-agent prompts
Shared task board: humans and agents can create, assign, claim, and close tasks
Cron jobs: schedule recurring agent runs; each run is a fresh chat (that can be continued)
Image/PDF attachments: agents understand images and PDFs and can show images inline
Conversation branching: edit any past message to fork the conversation
Notifications: get pinged (and waved at) when an agent finishes
Pre-tool-call safety hooks

Get Started (run it locally)

1. Prerequisites

You need Bun (v1.2+) and at least one of: the Claude Code CLI (Claude subscription) or the Codex CLI (ChatGPT subscription).

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Install at least one agent CLI
npm install -g @anthropic-ai/claude-code && claude  # then /login
npm install -g @openai/codex && codex login

2. Install & Run

git clone https://github.com/nmamano/isomux.git
cd isomux
bun install
bun run dev

That's it; nothing to build or deploy.

3. Open

Visit http://localhost:4000 in your browser. Click an empty desk to spawn your first agent.

Self-hosted Server Setup (Mac Mini style)

Isomux shines when you run it on your own always-on box/server (like a Mac Mini), and then access it from all your devices.

Same office for all your devices. Agents keep running even if you close the browser.

The easiest way is to use Tailscale (free, zero-config): your server serves Isomux on localhost:4000, and every other device reaches it at <TAILSCALE_SERVER_IP>:4000.

1. Install Tailscale

Install Tailscale on the server, your laptop, and your phone.

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

# Find your Tailscale IP
tailscale ip -4

Bonus: Instead of remembering an IP, rename your machine in the Tailscale admin console to something friendly, like my-mac-mini.

2. Access from laptop or phone

Open from any connected device:

http://my-mac-mini:4000

Tip: On your phone, use “Add to Home Screen” for a native app feel.

iOS Safari share menu with the “Add to Home Screen” option highlighted

3. Make it persistent

Give this prompt to one of your Isomux agents:

Set up Isomux as an always-on server. Create a systemd user service
that auto-rebuilds the UI on start and restarts on failure. Enable
lingering so it survives logout.

HTTPS Features (optional)

Some features require a secure context (HTTPS or localhost). Over plain HTTP on a remote host, the app works normally but the following won't be available:

Voice input: browser microphone access requires HTTPS
PWA install: "Add to Home Screen" on Chrome/Android requires a service worker, which requires HTTPS

These work out-of-the-box on localhost. To enable them over Tailscale, follow these steps.

1. Enable HTTPS in Tailscale

Open the DNS page of your Tailscale admin console. Enable MagicDNS if not already on, then enable HTTPS Certificates.

2. Allow Tailscale without sudo

sudo tailscale set --operator=$USER

3. Start the HTTPS proxy

Run this on the server (you can use the built-in terminal in Isomux):

tailscale serve --bg http://localhost:4000

--bg persists the proxy across reboots. Visit the HTTPS URL it prints (e.g. https://my-mac-mini.<tailnet>.ts.net) for voice input and PWA install.

How It Works

Isomux runs as a single Bun process on your machine. It uses the Claude Agent SDK to create and manage agent sessions — one per desk — with no subprocess juggling.

A WebSocket layer keeps every connected device in sync in real time. Open the same URL on your laptop and phone — both see the same office, same conversations.

Agent sessions persist across server restarts. Your agents pick up right where they left off.

There's no database, no cloud dependency, no API key. Isomux piggybacks on your existing Claude CLI authentication and inherits your global Claude skills.

For a deeper dive, see the Design and Architecture blog post.