relay

Relay

One Claude Code window. Every Claude account you own.

Your window plans and talks with you. Your other accounts do the heavy lifting.

Install · Use it in a conversation · How it works · FAQ · 中文

Why

A Claude Code window runs on one account, and that account's usage runs out. Relay keeps your window as the leader: it talks with you, plans and reviews. Heavy, self-contained jobs go to your other accounts, the workers, each running the official Claude Code under its own login and its own usage. You keep one conversation; the work spreads across your plans.

Features

Feature	What it does
Hand off	Say /relay <job> or "use relay for this". A free worker takes it and the report comes back to your window.
Memory	A named thread resumes the same worker session, even after it moved to another account. A project ledger tells every worker what the others did.
Usage at a glance	Every account's 5-hour and weekly usage and when it resets, read from Claude Code's own /usage.
A model per account	Run mechanical jobs on Haiku and save the big models for the work that needs them.
Safety net	When the leader hits its limit mid-task, Relay resumes the same session on the next ready account in the background.
Every worker at once	Several jobs run in the same folder and conversation at the same time, one per free worker; with every worker busy, a job waits for the first one to come free. Jobs that name overlapping folders (scope) take turns, so they never edit the same files together.
Native on macOS	A menu-bar app: template icon, frosted panel under the icon, running-job count next to it, open at login.
Updates reach open windows	Every tool call runs Relay's current code, so an update applies to conversations that are already open.
Local and private	Everything listens on 127.0.0.1. Relay never reads, copies or sends your credentials.

Install

You need Claude Code (the desktop app or the claude CLI) and Node.js 22 or newer.

git clone https://github.com/OvOhao/relay.git
cd relay
npm install
npm start

The R icon appears in the menu bar. Want to look around first, without touching your accounts?

npm start -- --demo

Build a real app (Relay.app and a .dmg for Apple silicon and Intel, written to dist/):

npm run dist:mac

The build is ad-hoc signed, not notarized. One you built yourself opens directly; a copied one needs System Settings › Privacy & Security › Open Anyway once, or xattr -dr com.apple.quarantine /Applications/Relay.app.

npm start runs it as a tray app; npm run dist builds an installer and a portable exe. The Windows build is tested in CI but has not been tried on a real Windows machine yet.

Set up

1. Click the menu-bar icon. Accounts › Add account for each Claude account you own; each one signs in once through Claude Code's own login, in a browser profile of its own.
2. Connect. Relay backs up ~/.claude/settings.json, then adds two hooks (StopFailure, SessionStart), an MCP server relay and a skill ~/.claude/skills/relay.
3. Start a new Claude Code session (open ones don't pick the tools up). claude mcp list should show relay ✔ Connected.

Use it in a conversation

Just ask, in any new Claude Code session:

/relay write unit tests for src/parser and make npm test pass

Which relay accounts are free right now?

Continue the auth-refactor thread: also handle expired sessions.

Read the relay ledger for this project: what did the workers do?

Claude calls the tools for you:

Tool	What it does
relay_run	Hands a job to a worker: task, context, cwd, an optional thread to continue, read_only, account, model, title, scope (the folders it changes), preset (a task preset, e.g. security). Returns the worker's report. Call it several times in one turn to run jobs in parallel.
relay_status	Who is the leader, which workers are ready, how much usage each has left; the threads in a project.
relay_ledger	Everything workers did in a project, to get back on track after a long break or a compacted context.

While a job runs, the number next to the menu-bar icon counts it and the panel shows which account is on it and what it is doing.

What workers may do

Workers run in the background, so nobody is there to approve a command. Settings decides what they may do:

• Permission mode. Auto works like your own window: routine commands run, risky ones are refused. Edit files, Do everything and Read only are there too.
• Commands workers may run. Claude Code permission rules such as Bash(npm test).
• Commands workers may never run. Refused however the command is written: a full path, ./, or inside cd … && …. Use it for what only you or your own window should do, such as Bash(git push *).
• Jobs. One job at a time per folder (off by default) and Jobs per worker at once (1 by default).
• Task presets. Background a worker gets in its system prompt for one kind of work, so it reads a legitimate task correctly. The built-in Security research preset is applied when the dispatcher asks for it (preset: "security") or when a job mentions one of its keywords (vulnerability, exploit, prompt injection, red team, …). Write only what is true about your work: a preset gives context, it lifts no limit.

Relay writes these rules into each worker account's own settings.json (your settings plus the rules) and keeps them current. Your own ~/.claude/settings.json is never changed.

How it works

flowchart LR
  L["Your Claude Code window<br/>(leader)"] -->|"relay_run · hooks"| R
  subgraph Mac["Your Mac · 127.0.0.1"]
    R["Relay<br/>threads · project ledger · usage"]
  end
  R --> W1["Worker A<br/>official Claude Code<br/>own login"]
  R --> W2["Worker B<br/>official Claude Code<br/>own login"]
  W1 -->|report| R
  W2 -->|report| R
  R -->|report| L

• Leader and workers. The account of the window you are in is the leader; Relay recognises it from the session. Every other account is a worker.
• Threads and the ledger. Workers cannot see your conversation, so the leader writes a self-contained brief. A thread name resumes the same worker session; the project ledger goes into the next worker's prompt.
• Usage. Each account's numbers come from Claude Code's own /usage, read in the background and live while the panel is open.
• Safety net. A StopFailure hook notices a plan limit and Relay continues the session with --resume on the next ready account, then tells you.

Privacy and safety

• Never reads, copies or sends your Claude credentials. Sign-in only through claude auth login; on macOS each login stays in the Keychain, managed by Claude Code.
• Local only: the panel, its API and the hooks listen on 127.0.0.1. Nothing is proxied and the Claude Code binary is not modified.
• Settings › Remove Relay takes it all out again and restores your settings; saved sign-ins stay unless you tick the box.
• Use only accounts you own. Each account's limits and terms still apply: the Consumer Terms, the Usage Policy and your organisation's terms for a Team or Enterprise seat.

FAQ

Another tool is deleting its login. On macOS Claude Code keeps one Keychain item per login folder; some multi-account tools (for example the clauth plugin) delete every such item they don't recognise whenever a Claude Code session starts. Relay shows a warning when it sees clauth enabled. Turn that tool off, then sign in again.

A real plan-limit takeover (tested with simulated limit events and a fake claude), Apple notarization, and a real Windows machine.

Development

npm test                            # 87 tests against a fake claude: no usage spent
node src/dev.js --demo              # the panel in a browser
npx electron scripts/make-icon.js   # icons from build/logo.svg and build/mark.svg
npx electron scripts/screenshots.js # the screenshots above, from the demo

src/core holds accounts, limit detection and takeover, usage, project memory, workers, hooks and connect, and macOS support; src/mcp.js is the MCP server, src/server.js the local API, ui/ the panel and src/main.js the Electron shell.

Credits

Relay includes code by ZhengGao-30, used under the MIT license. It is an independent project, not made by or affiliated with Anthropic.

MIT