relaybay MCP server
Commit Nov 13, 2026Provides a live dashboard and MCP server to track and manage multiple Claude Code sessions across various repositories and projects.
Also known as Codenator81/relaybay
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- MIT
What is relaybay MCP?
relaybay provides a live dashboard and MCP server to track and manage multiple Claude Code sessions across various repositories and projects.
Summary generated from the project's README
About relaybay MCP server
Managing multiple Claude Code sessions across various repositories is made easier with relaybay. This tool provides a live dashboard and an MCP server that allows you to track projects, tasks, and stages in real time. Instead of checking individual terminals, you can monitor progress through a visual board that updates via Server-Sent Events, accessible on a desktop, browser, or phone.
Developers can use the desktop application or run the server via command line using uvx or pipx. The system is local-first, using SQLite and binding to 127.0.0.1 for privacy, with no telemetry. It requires a token for connection, which you can generate using the relaybay token command to add the MCP server to Claude Code. The server supports Windows, macOS, and Linux, offering a centralized way to review agent work, accept or reject checklists, and manage environment permissions through a policy-based system.
What you can do with it
- 1Monitor multiple active sessionsTrack which Claude Code sessions are working, which are waiting for user input, and what they have accomplished without opening every terminal.
- 2Review agent work visuallyVerify completed tasks by reviewing checklists and screenshots attached by the agent before accepting the work.
- 3Communicate with coding agentsSend instructions or feedback directly to a running session through task comments.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecodenator81/relaybay is public and reachablegithub.com/codenator81/relaybay ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/codenator81/relaybay ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubrelaybay
A live board and MCP server for people who run many Claude Code sessions across many repositories. Sessions report their work through MCP tools; you watch projects → tasks → stages → reports update in the browser, on the desktop or on your phone.
Status: 0.9, early. relaybay is built for my own workflow first and changes quickly; Windows is what it runs on every day, macOS and Linux are beta. Expect rough edges; issues and ideas are welcome.

Why relaybay
- One board for every session. Ten repositories, ten Claude Code sessions: the board shows which one is working, which one waits for you and what it did, without opening each terminal.
- Accept the work by eye. Agents write a checklist of what to check and attach screenshots; you accept or reject step by step, and your comments reach the agent in its next turn.
- Local and plain. One process, SQLite, bound to
127.0.0.1, token-protected, no telemetry; an installer for Windows, macOS and Linux, oruvx relaybayfrom the command line.
The case of the missing "yes"
Tuesday, 6 p.m. Eleven sessions open in the desktop app, each in its own project. One of them asked a question at noon and has been waiting ever since. Which one? The chat list says "idle" eleven times. The coordinator session has the answer, but only the first lines of each report, and it is retelling them from memory. A push went out that nobody remembers approving. A plan was accepted and the session that wrote it never heard.
The suspects: too many chats, too few witnesses. The desktop app is a fine room for one conversation; Projects keep the files of one job together. Neither keeps the record of what eleven agents asked, were told and were allowed to do.
relaybay is that record. Every task is a card, every question has a default and an owner's answer, every push waits for a button on the board, and every turn's report lands in full. Case closed — and the next one starts on the card, not in a chat you have to find first.
Quick start
uv tool install relaybay # or: pipx install relaybay · or run it once: uvx relaybay
relaybay serve # prints the board's login link and the MCP URL
relaybay setup # shows how it connects Claude Code (then --apply --expect <hash>)
Just looking? relaybay demo --home ./relaybay-demo fills a folder with two made-up projects, then
relaybay serve --home ./relaybay-demo --port 8766 shows them.
Open the login link once; the browser keeps a cookie. relaybay token prints the token again with
the claude mcp add … command for Claude Code. Docker, Windows/macOS/Linux details and a procedure
your coding agent can follow for you:
Install ·
Install with your coding agent.
Something off? relaybay doctor.
Install
The desktop program (a tray icon, the board in a window, the server inside, start at login) comes as an installer on each release. The installers are not signed with a certificate, so the OS warns once:
- Windows (x64): run
relaybay-<version>-windows-x64-setup.exe. It installs for your user only, without admin rights, into%LOCALAPPDATA%\Programs\relaybay. SmartScreen says "Windows protected your PC": click More info, then Run anyway. - macOS (Apple silicon, beta): open
relaybay-<version>-macos-arm64.dmgand drag relaybay to Applications. The first start is blocked: System Settings → Privacy & Security → Open Anyway (macOS 15 no longer offers right-click → Open), or runxattr -dr com.apple.quarantine /Applications/relaybay.app. - Linux (amd64
.deb, beta):sudo apt install ./relaybay_<version>_amd64.deb. A tray icon and the board in your browser (no window); GNOME needs the AppIndicator extension for the tray.
Then connect Claude Code from the installed program: relaybay setup, then
relaybay setup --apply --expect <hash> (or Settings → Reconnect Claude Code in the program).
Check the files with SHA256SUMS.txt from the same release if you like.
The command line (any OS, Python 3.12+): uv tool install relaybay, pipx install relaybay,
uvx relaybay, or the Docker image ghcr.io/codenator81/relaybay. Details:
Install; a server in Docker with the
program as its client:
how-to.
Documentation: codenator81.github.io/relaybay · Specification (how it behaves now) · Roadmap · Architecture
Features
- Board — projects with per-stage counts; per project, columns
plan → dev → review → test → live → doneon two pages with cards showing only the essentials: key, tracker badge, an "open in desktop" icon when a desktop session works on the task, title, waiting-on person, branch and the next step (a Compact toggle leaves key, tracker, title and who it waits on, with a chevron per card). Drag cards to set their order in a column or to move them to another stage (or use the card's ⋯ menu from the keyboard or a phone). Click a card to open the task in a dialog over the live board (its own URL,/p/<project>?task=<key>, full screen on a phone): description and progress in full, reports, session history, "Open in desktop", unbinding the session and editing the task. Each task also has a page of its own (/t/<key>). Live updates over Server-Sent Events, catch-up after sleep or a dropped connection, a stage tab bar on narrow screens; ← / → switch the two board pages. - Repositories and "Open in VS Code" — a project lists its repositories (Stands & access, or
project_upsert(repos=…)); each card shows the ones the task touches with its pull requests and an "Open in VS Code" link, linked by agents (task_update(repos=…, prs=…)) or by the hooks from the folder a bound session works in. - Quick switcher and saved filters — Ctrl+K (Cmd+K on macOS) finds any task, project or session by a few letters; board filters by stage, waiting-on and session stay in the URL and can be saved as chips on the board and items in the sidebar.
- Review — agents write what you should check by eye as a checklist and attach screenshots
(
review_steps_set,attach_file); you accept or reject each step in the task's Review tab, look at screenshots full screen, draw on them and drop numbered pins for the agent, paste your own with Ctrl+V, and each decision reaches the agent as a comment. Tasks waiting for acceptance are in the Inbox's Review queue; an optional browser notification (Settings → Notifications) says when one arrives, and the desktop program's tray says it with no tab open. How agents make screenshot files: Screenshots for review. - Next step that keeps up — sessions pass the next step and who acts next together with a stage change or a report; a next step left over from before the last stage change shows muted and marked "stale".
- Done column and archive — the
donecolumn shows tasks closed in the lastdone_window_days(default 7); older ones are archived and come back with "Show archived" or a search by key or title (/p/<project>?archived=1,?q=…). Archive on a done card sends it there at once, Back from the archive brings it back for another window. Done cards hide "waiting on" and the next step. - External tracker mark — a task can carry its issue in any tracker (tracker name, issue key,
optional link) and a "work log entered" mark. The card shows the issue as a badge at the top (a
link when a URL is set, ✓ once logged). With
require_tracker_log = truea done task without the mark shows "not logged" and stays out of the archive until it is marked. Every issue key a task has had is kept in its tracker history (task dialog,/t/<key>,task_get), and new work on a logged task (a report, a progress change, a move back fromliveordone) clears the mark again, so it always means "the log covers everything done". - Comments to agents — write a comment on a task (dialog or task page) and the agent of the
bound session gets it through its hooks with its next prompt or tool call; the thread shows
"sent / delivered / read" live,
Stopreminds the agent (at most twice) until it acknowledges, and agents answer withcomment_add(their replies land in your Inbox). An opt-in wake-up hook (relaybay setup --apply --wake, Claude Code 2.1.309+) wakes an idle session for a new comment or your acceptance of its plan. - Intake and backlog — a watcher you run (Telegram and e-mail examples in
examples/intake/) posts chat and mail messages; relaybay ties them to the waiting task and marks it "answer received", and only a trusted source on a task with autonomy on lets the agent go on by itself. Findings and ideas wait on the backlog until you plan them (guide). - Stands & access — per project, the local, test and live environments with their base URL and
how agents reach them (ssh alias, kube context, database host, GitOps repository, log links),
stored as references only, never secrets; agents' permission level per environment (
none,read,ask,full; live isreadby default), changed only by you on the board (agents propose withenvironment_propose). ThePreToolUsehook warns about or blocks a command aimed at an environment its level forbids — a safety net against mistakes, not a sandbox — and every agent tool call that touches live lands in a journal (the Audit page, with filters). A No live now switch on a session denies it any touch of live at its next tool call. - Policy as data — the levels, the guard and the secret checks come from a policy, not from
the code: a preset (
default,strict,trusted), an optionalpolicy.jsonin the data directory and project or environment layers, each value showing which layer set it (Settings → Policy,policy_get). A trusted machine can give agents full access with the guard only journaling and keep harmless test passwords on local and test stands (masked, not sent to agents unless you say so, never on live). Agents propose changes withpolicy_propose. - Docs & rules — per project, versioned documents (spec, status, task notes, runbooks) with section anchors and diffs, edited on the board or by agents, linked from tasks down to a section, or pointing at the repository they live in; decisions that supersede each other instead of being deleted, memory notes and blocks agents keep for the next session, full-text search over all of it, and the rules.
- Plan and checkpoints — agents write the task's plan (
plan_set) and mark each step done with one line,as plannedordeviation: why; you accept the plan in the task's Plan tab, deviations stand out on the card, and the agent's own Claude Code todo shows under the current step. By default a move todevneeds an accepted plan unless the task is sizeS. The plan stays alive: work added after a report is a new step (plan_step_add, the acceptance kept) and takes the task back todev. - Usage — tokens by session and model, per day and week and per project, read locally from the
Claude Code transcripts the hooks report: only
usagenumbers and the model name are kept, never prompt or output text, and no prices or quotas. Turn it off withusage_enabled = false. - MCP server — Streamable HTTP at
/mcpin the same process: create and update tasks, change stages, keep a task's description and progress summary current, add reports and decisions, bind and unbind sessions, get a markdown snapshot of a project. A plain session name never replaces a task's desktop session binding: it becomes that session's alias.task_patchtakes any task fields as one JSON object, so clients with an older tool schema can still set new fields. - Working rules — the server tells every connected session how to work with the board (MCP
instructions: read the snapshot, pick a task, keep next step / waiting on / progress current,
report as
state · size · gist) and serves the rules as data: report format, what a stage move needs (by default an accepted plan beforedevunless the task is sizeS, a report beforetest,progressbeforedone), a description template and free-text guidance. Global rules come fromconfig.toml, a project can override them; agents read them throughrules_getorrelaybay://rules/<project>, andproject_snapshotstarts with the rules version. Rules are versioned: agents change them withrules_proposeand the owner accepts or rolls back in Settings → Rules. A stage move that misses a rule succeeds with a warning (or is refused withrules_mode = "strict"), in MCP responses and on the board. - Runs on a card — relaybay can start your own unmodified
claudeon a card, on your machine only, under your own subscription sign-in; it never signs in for you or reads credentials, and refuses API-key sign-ins unless you allow them in Settings. The card's Agent block starts the first turn in the project folder or one of its repositories, each repository in a new git worktree (with its untrackedCLAUDE.mdand.claude/copied in, never added to git) or used in place, with a brief built from the card; then each Continue resumes the same Claude Code session (--resume); a text sent during a turn waits for it, Stop kills the turn's whole process tree, and the card shows the status, the Claude session id and each turn's tokens. The run's hooks report to its own session row on the card; whenrelaybay setupdid not install them, the run passes them itself. Between turns you can open the session in the Claude desktop app (on Windows; elsewhere the card shows theclaude --resumecommand) and hand it back, and change the permission mode, model and effort for the next turns. Coordinator sessions may start runs withrun_startand lower a run's mode withrun_settings; project defaults (model, effort, permission mode, allowed tools, project folder) are on Stands & access, the sign-in switch in Settings → Agents. relaybay runsgit worktree add, never a commit or push. - Questions to you — an agent asks with
question_ask, always with a default; the question shows in your Inbox and on the card (a blocking one also in the tray), and only your answer on the board closes it. A run waits on a blocking question and your answer starts its next turn, verbatim; a desktop session gets it as an owner comment. A non-blocking question closes with its default at its deadline. "Look at this" questions carry the URL of a screen the agent brought up and the test account's name, never a password. - Approvals — a run's push, PR merge or change on a stand waits for your Approve on the
board: the guard denies the call and opens a request (or the agent asks with
approval_request), the request shows in your Inbox, on the card and in the tray, and your decision reaches the agent as its next turn or an owner comment. One approval allows one matching call, run alone, and a push approval names its branch. What needs one is policy data per project (approvals; desktop sessions only withapprovals.desktop); a change on live always does. - Desktop program — an installer per OS puts relaybay in the tray with the board in its own window (on Linux in the browser) and the server inside: start at login, Restart server and Logs in the tray menu, a daily update check with Update to X.Y.Z that downloads and checks the release's installer, a backup of the data before a new version migrates it, and an external server mode that makes the program and the CLI clients of a relaybay running elsewhere (for example in Docker).
- Local and private — one process, SQLite, binds to
127.0.0.1, token-protected, no telemetry, no CDN. The only outbound calls are a daily check of the latest GitHub release (a line in the Inbox, or a dot on the tray icon, when a newer one is out) and, when you click Update in the program, the download of that release's installer.update_check = falseturns the check off: inconfig.tomlfor the server, indesktop.tomlfor the program.
Bring your markdown
Briefs, a task registry, task notes and memory notes in markdown files come over with a dry run first, and go back out for git history and backup: import and export.
relaybay import ./notes # the plan and its hash; writes nothing
relaybay import ./notes --apply --expect <hash> # write exactly that plan
relaybay export ./notes --apply # the board back to the same layout
Connect Claude Code
claude mcp add --transport http --scope user relaybay http://127.0.0.1:8765/mcp \
--header "Authorization: Bearer <token>"
user scope adds relaybay once for all repositories. See
docs/connect-claude-code.md for .mcp.json and a short instruction
snippet for your project's CLAUDE.md / AGENTS.md that tells the agent when to call the tools.
Live session status (hooks)
relaybay setup # what it found, the exact diff and its hash
relaybay setup --apply --expect <hash> # adds relaybay's hooks to ~/.claude/settings.json
relaybay setup --check # end-to-end check, one ok/FAIL line per item
The hooks let the board show whether each session is working, waiting for you, idle or gone,
unbind a session from its task when it ends, and hand your comments to the agent of the task's
session. Setup adds only its own entries (other hooks stay as
they are), never writes the token into the file, and --remove takes them out again. The same plan
and buttons are on the board under Settings → Integrations. Hooks stay silent when relaybay is not
running. Details: docs/connect-claude-code.md.
Schema changes and long-running sessions
A Claude Code session keeps the parameter schema of a tool it already loaded, even after relaybay
restarts and the client reconnects: new tools appear, but new parameters of an existing tool do
not. Use task_patch(task, fields={...}) for fields your client does not know yet (the allowed
names are at the end of task_get and in relaybay://schema/task), or refresh the schemas by
reconnecting the server in the client (/mcp in the CLI) or starting a new session. See
docs/mcp-tools.md. A release only adds
to the MCP tools; a removal is announced first by a Deprecated: … line
(contract).
The tool reference is in docs/mcp-tools.md.
relaybay MCP questions
What is relaybay used for?
It is a live board and MCP server designed for users running many Claude Code sessions across multiple repositories, allowing them to monitor projects, tasks, and reports.
Does relaybay collect my data or telemetry?
No, it is local and plain, using SQLite and bound to 127.0.0.1 with no telemetry.