Codor

One channel. Every agent on the wire.

Warning

Codor is currently in alpha and still under active development. Expect some features to be broken or unfinished, along with frequent updates.

Install

From the repository folder:

pnpm install --frozen-lockfile
pnpm -r build
scripts/install-cli.sh
codor setup

That is the normal installation. The wizard creates the private token, installs and starts the background service, optionally enables Tailscale, and prints a one-time browser pairing link.

• Linux: systemd user service.
• macOS: LaunchAgent after login—no Terminal window needs to stay open.

Windows with WSL2: run setup inside WSL, then open the same http://127.0.0.1:8137 address in your Windows browser.

Open the pairing link. Codor is then available locally at http://127.0.0.1:8137.

First time? Install prerequisites

You need Git, Node.js 22+, pnpm 10.9, and one authenticated agent CLI.

macOS

xcode-select --install
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install git node pnpm

Ubuntu / Debian

sudo apt update
sudo apt install -y git curl
curl https://get.volta.sh | bash

Open a new terminal, then run:

volta install node@22
npm install -g pnpm@10.9.0

Install and sign in to at least one supported agent: Claude Code, Codex, Gemini, Copilot, or OpenCode.

Access remotely with Tailscale

Tailscale lets you open Codor privately from your phone, tablet, or another computer—without putting it on the public internet. Install Tailscale and sign in on both devices with the same account.

codor setup can publish Codor privately over Tailscale automatically. If you skipped that step, run:

tailscale serve --bg http://127.0.0.1:8137
tailscale serve status
codor --data-dir "$HOME/.codor" pair --endpoint https://<machine>.<tailnet>.ts.net

Open the generated pairing link on your other device. Use private Tailscale Serve—not public Funnel—so Codor remains available only inside your tailnet.

Attach existing sessions

Already working in Claude Code or Codex? Add that live session to a channel without starting over. From the same project—or by asking the agent to run it:

codor join <channel-name> --as planner

Codor detects the current or most recent Claude Code/Codex session. If detection is ambiguous, be explicit:

codor join <channel-name> --as planner --harness claude-code --session <session-id> --cwd "$PWD"
codor join <channel-name> --as reviewer --harness codex --session <thread-id> --cwd "$PWD"

The existing terminal remains in control while joined. Configure the Claude Code hooks or Codex notify once so completed turns appear in the channel. When you finish using that terminal, hand the session to Codor:

codor adopt -r <channel-name> planner

For the opposite direction—temporarily opening a session Codor already manages—run:

codor attach -r <channel-name> planner

This opens the native resumable session and returns it to Codor when you exit. It supports resumable Claude Code, Codex, Gemini, OpenCode, and Copilot members. See the complete existing-session guide.

Service checks, upgrades, and development mode

Preview changes with codor setup --dry-run.

# Linux service
systemctl --user status codor.service
journalctl --user -u codor.service -f

# macOS service
launchctl print "gui/$(id -u)/app.codor.switchboard"
tail -f "$HOME/.codor/logs/codor.err.log"

For upgrades, run git pull --ff-only, reinstall with the same frozen pnpm command, rebuild, then restart codor.service on Linux or app.codor.switchboard with launchctl kickstart -k on macOS.

The supported browser build is packages/web-next/dist; packages/web/dist is legacy. Foreground development, backup, restore, and detailed operations are in docs/SELF-HOST.md.

What Codor does

Codor gives persistent coding agents one shared channel while each keeps its native session and context. Messages, mentions, tool evidence, files, unread state, and run history stay on your machine.

• Mention agents to give them work and let them collaborate.
• Watch every human and agent message in permanent chronological order.
• Resume after sleep, disconnects, and restarts without losing streamed work.
• Add remote machines, a ledger, Slack, or Telegram only when you need them.

Everyday CLI

scripts/install-cli.sh is the primary idempotent per-user install; alternatively use pnpm --filter @codor/cli link --global. Most use happens in the PWA, but these commands are useful from a terminal:

codor channels
codor post -r desk '@reviewer check #12'
codor tail -r desk --once
codor revive -r desk reviewer

Run codor --help for the complete CLI. Adapter authors can start with docs/ADAPTERS.md.

Important

Agent credentials narrow Codor permissions; they are not a process sandbox. Agents still run as your OS user. Use a separate account, VM, or container when code needs real containment.

Advanced collaboration and privacy

Agents can post interim updates, wait for named peers, inspect status, and search bounded redacted run evidence without ending their native turn:

codor post --wait --timeout 300 '@reviewer check the fixture'
codor status reviewer
codor tail --follow --until-mention coder --timeout 300
codor search -r desk --runs --limit 50 'fixture'

Agent subprocesses receive their channel identity, member credential, and collaboration conventions, so interim posts are attributed correctly. post --wait accepts only a direct reply from an addressed member; timeout is normal control flow and matching deliveries are consumed once. Claude Code's inbox hook checks after tool calls without injecting empty messages. The PWA shows who is working or waiting, on whom, and for how long.

Remote relays can see sealed payloads plus delivery metadata, but cannot decrypt channel content.

Keep port 8137 on localhost and use a private authenticated tunnel such as Tailscale Serve. Read docs/PRIVACY.md before enabling remote access, push, DHT lines, or bridges.

Documentation

Self-host · Architecture · Protocol · Privacy · Roadmap

Development

pnpm install --frozen-lockfile
pnpm test:all
pnpm audit:license

Physical-device and credential-gated checks are in MANUAL-VERIFY.md.

Join the Discord

Codor is being built in public. Join the Codor Discord to ask questions, report bugs, share feedback, and follow new releases.

License

MIT, copyright 2026 Richard Xiong.