bridge

Tiny tmux command center for live terminal agents.

No SDKs. No APIs. No daemon. Just a global bridge shell command + tmux panes.

Install globally

Recommended npm install:

npm install -g @riverline/bridge-cli
bridge setup

npm install -g installs the bridge CLI. bridge setup explicitly installs or updates:

~/.bridge/config.toml
~/.codex/skills/bridge
~/.claude/skills/bridge

Bridge intentionally does not use npm postinstall hooks to mutate your home directory. Run bridge setup when you want skills/config installed.

Global config

Bridge stores worker command presets in:

~/.bridge/config.toml

Defaults:

[kind.codex]
cmd = "codex"
resume = "codex resume {id}"

[kind.claude]
cmd = "claude"
resume = "claude --resume {id}"

So agents/skills can spawn workers without passing explicit shell commands:

bridge spawn codex_a --kind codex --cwd /repo
bridge spawn claude_a --kind claude --cwd /repo
bridge spawn codex_old --kind codex --resume <SESSION_ID> --cwd /repo

Manage config:

bridge config show
bridge config set codex.cmd "zsh -lic 'your-codex-alias'"
bridge config set claude.cmd "zsh -lic 'your-claude-alias'"
bridge setup --reset-config   # reset config to package defaults and reinstall skills

Session mapping model

bridge is global. New bridge rooms should use named sessions stored outside your repos:

~/.bridge/sessions/<session-name>/
  state.env              # tmux session/window/pane + agent metadata
  session.toml           # human-readable room metadata
  agents.toml            # human-readable agent roster
  events.jsonl           # audit event stream
  messages.md            # sent message log
  AGENT_PROTOCOL.md      # coordination protocol injected by bootstrap
  to-<agent>             # convenience wrappers generated from state

This lets the same project run multiple bridge rooms in parallel without creating project-local .bridge/ folders. Use human names like staging-drift, pr-review, or branch-sync:

bridge session create staging-drift --project /path/to/project --use
bridge --session staging-drift master here --name lead --kind claude
bridge --session staging-drift spawn codex_a --kind codex --cwd /path/to/project
bridge --session staging-drift status

Legacy project-local .bridge/state.env rooms still work for backwards compatibility. If no --session is passed, bridge first looks for project-local legacy state, then falls back to bridge session use <name>.

Core model

Every pane is just an agent with metadata:

name + role + kind + pane + cwd + cmd + groups

Examples:

lead       role=master  kind=claude  pane=%27
worker1    role=worker  kind=codex   pane=%31
reviewer   role=reviewer kind=claude pane=%32

kind is metadata only. bridge does not hardcode Claude/Codex behavior.

Provider session ids are stored in agents.toml when known. --resume <id> automatically records that id; use --session-id <id> when adopting/registering an existing Codex/Claude session and you already know its provider id.

Conductor layout

For orchestration, the master must run inside tmux. Bridge keeps the layout as:

┌─────────────────────┬─────────────────────┐
│                     │ worker-1            │
│                     ├─────────────────────┤
│ master              │ worker-2            │
│                     ├─────────────────────┤
│                     │ worker-3            │
└─────────────────────┴─────────────────────┘

• Master stays on the left.
• Workers stack on the right.
• Bridge reapplies this layout after every spawn/stop.
• Bridge also titles tmux pane borders as name [role/kind], e.g. lead [master/codex].
• bridge spawn waits for Codex/Claude workers to look ready before returning, so the first task/bootstrap message does not get pasted during startup. Override with --no-wait / --force-ready, or tune with --wait-timeout / --ready-pattern.

Skill UX

After setup, restart Codex/Claude sessions if they do not see the new bridge skill. Day-to-day, ask the master agent naturally:

Use bridge. You are the master. Split this task across two Codex workers and one Claude reviewer, coordinate them, collect reports, and stop workers when done.

The skill should run the preflight, register the master pane, spawn workers, bootstrap, assign tasks, collect reports, and summarize back to you.

Recommended master workflow

Start/resume your master session inside a clean tmux window/session.

Claude master example:

cd /path/to/project
tmux new -s bridge-master
claude --resume <CLAUDE_SESSION_ID>

Codex master example:

cd /path/to/project
tmux new -s bridge-master
codex resume <CODEX_SESSION_ID>

From inside the master agent/session, register the current pane:

bridge master here --name lead --kind claude

or:

bridge master here --name lead --kind codex

Then spawn workers:

bridge spawn service_a \
  --kind codex \
  --role worker \
  --cwd /path/to/projects/service-a

bridge spawn reviewer \
  --kind claude \
  --role reviewer \
  --cwd /path/to/projects/service-b

Bootstrap everyone:

bridge bootstrap

Broadcast a task:

bridge broadcast --role worker "Investigate staging/main drift. Report only. No edits."

Ask workers to report back to master:

bridge collect --from role:worker --to lead

Existing two-pane workflow

If sessions are already running in tmux panes:

tmux list-panes -a -F '#{session_name}:#{window_index}.#{pane_index} #{pane_id} #{pane_current_command} #{pane_current_path}'
bridge adopt --agent codex:%27 --agent claude:%28
bridge bootstrap

Useful commands

bridge session create staging-drift --project /repo --use
bridge session list
bridge --session staging-drift status
bridge status
bridge room status
bridge capture worker1 --last 300
bridge wait worker1 --timeout 45
bridge send worker1 "Task update..."
bridge send --force-ready worker1 "Task update even if readiness got stuck..."
bridge broadcast --kind codex "Codex-only instruction..."
bridge stop worker1
bridge layout apply
bridge titles apply
bridge titles off
bridge attach
bridge doctor

Automated releases

Releases are automated from main with GitHub Actions and semantic-release. Configure the repository secret:

NPM_TOKEN=<npm automation token, or granular token with publish access and 2FA bypass>

Use Conventional Commits to control version bumps:

fix: patch release
feat: minor release
feat!: major release
BREAKING CHANGE: major release

The release job syncs package.json, package-lock.json, and the bash CLI VERSION inside CI before publishing, then publishes to npm and creates a git tag/GitHub release.

If the release workflow fails authentication, add or rotate the NPM_TOKEN repository secret and rerun the workflow. If npm returns EOTP, recreate the token with 2FA bypass enabled; normal login tokens still require a browser OTP.

Cleanup

Stop a worker pane and remove it from state:

bridge stop worker1

Stop a bridge-managed session:

bridge stop

For conductor/adopted rooms, bridge stop removes the mapping but leaves tmux running. To force kill the tmux session:

bridge stop --kill-session