COMPINION02GitHub

YOUR MAC. YOUR AGENTS. YOUR TAILNET.

Your coding agents left the desk.

ComPInion turns the Pi and Codex processes running on your Mac into one private, mobile-first switchboard—without moving your code or agent runtime to a cloud service.

Start the switchboard ↓Read the source ↗
02
native agent engines
01
shared mobile console
00
public ingress routes
PHONE
MAC
ComPInion Codex session list running in a phone-sized browser
LIVE PRODUCT / 01854 sessions.
One pocket.
2AGENTS
AWAKE
TAILNET
ONLY

THE AGENT STAYS WHERE THE CODE LIVES.

The phone is a control plane,
not a second computer.

01 / SIGNAL PATH

Private by topology.

The browser never speaks Pi RPC or Codex JSON-RPC. A small Bun host owns those privileged local processes and exposes a narrow intent-and-event API.

04
▥

Your phone

Sessions, chat, tools, control

HTTPS + SSE
03
⌁

Tailscale Serve

Private TLS inside your tailnet

LOOPBACK
02
B

Bun gateway

Policy, process ownership, normalization

JSONL STDIO
01
⌘

Pi / Codex on Mac

Your code, credentials, sessions, tools

BOUNDARY NOTE

The web servers bind to 127.0.0.1. Tailscale Serve terminates private HTTPS. No Funnel. No public listener. No browser access to raw agent protocols.

02 / HOW COMPINION WORKS

Mac to first task.
Follow every step.

This is the complete path from a fresh checkout to controlling your first local coding-agent session from the phone.

  1. 01MAC · ONCE

    Install and sign in

    Install ComPInion with Bun. Make sure Tailscale is connected, then authenticate the engine you want to control.

    TERMINAL$bun install$codex login status # Codex only

    DONE WHENYour Mac has the web console and an authenticated local agent runtime.

  2. 02MAC · ONCE

    Install the one command

    Link ComPInion globally, then install its macOS service. The supervisor starts at login, health-checks both native engines, and restarts crashes automatically.

    TERMINAL$bun link$companion install

    DONE WHENThe switcher listens on 4316; Pi and Codex are online behind it.

  3. 03MAC · ONCE

    Open the private route

    Tailscale Serve adds one private HTTPS address in front of the unified control plane. It stays inside your tailnet—never use Funnel.

    TERMINAL$tailscale serve --bg --https=8442 http://127.0.0.1:4316$companion status

    DONE WHENOne private URL reconnects after network loss; the service starts again after Mac login.

  4. 04PHONE

    Open ComPInion

    Turn on Tailscale on your phone and open the single private URL printed by ComPInion. Save it to your home screen for app-like access.

    ON SCREEN

    →Open → https://your-mac.your-tailnet.ts.net:8442

    →Choose → Pi or Codex

    DONE WHENThe engine switcher loads without exposing any gateway publicly.

  5. 05PHONE · FIRST SESSION

    Pick a project and access

    Choose Pi or Codex, tap the orange +, browse to a project—or create its folder—then select the access and trust you intend to grant.

    ON SCREEN

    →Choose engine → + → choose folder

    →Choose access → choose trust → Start

    DONE WHENComPInion starts the native agent inside exactly that working directory.

  6. 06PHONE · EVERYDAY

    Run, steer, approve, resume

    Send the first task in Chat. Follow Tools for live work, answer approvals when needed, and use Sessions to move between active or sleeping agents.

    ON SCREEN

    →Chat → send / steer / follow up

    →Tools → inspect / approve

    →Sessions → sleep / resume / archive

    DONE WHENThe Mac keeps working while the phone remains your focused control surface.

06 / 06YOU ARE CONNECTED.

Close the laptop lid only if macOS is configured to stay awake; the agent and Bun gateway must keep running on the Mac.

03 / NATIVE ENGINES

One switchboard.
Two protocols.

ComPInion does not pretend the engines are identical. Each adapter preserves its native lifecycle, then maps it into a shared session language.

π

RPC / JSONL

Pi

READY

One isolated Pi child per active workspace. Native events become messages, tool traces, lifecycle receipts, and extension dialogs.

  • AgentSession → session
  • agent_settled → ready
  • extension_ui_request → phone dialog
C

APP-SERVER V2

Codex

READY

One long-lived Codex app-server powers many persistent threads. JSON-RPC requests and notifications are normalized behind the same UI.

  • Thread → session
  • Turn → agent run
  • server request → phone approval

04 / CONTROL SURFACE

The useful parts of
the terminal, recomposed.

01

Sessions

Create in any allowed folder, search the archive, wake, sleep, rename, fork, clone, or archive.

02

Live runs

Stream agent messages, reasoning, plans, tool output, diffs, token usage, retries, and compaction.

03

Intervention

Prompt, steer mid-run, queue a follow-up, interrupt, answer questions, and approve sensitive work.

04

Control

Choose models and effort, change trust modes, inspect history trees, run shell commands, and export HTML.

APPROVALS / LIVE

Sensitive work waits for you.

Codex command and file-change requests, permission elevations, MCP elicitations, and Pi extension questions are translated into explicit phone dialogs.

COMMAND APPROVAL NOW
CODEX WANTS TO RUNbun run typecheck

Working directory
…/Personal/ComPInion

05 / START LOCAL

Three commands.
Then pocket it.

Install with Bun, start the engine you want, and proxy its loopback port with Tailscale Serve. Your agent credentials stay in their existing local stores.

COMPINION — ZSH
01bun install
02bun run companion
03bun run companion:install
HOMEhttp://127.0.0.1:4316TAILNET :8442
ENGINESPI + CODEXAUTO RESTART

KEEP THE RUNTIME. LOSE THE CHAIR.

Take your agents
with you.

VIEW ON
GITHUB↗