Metadata-Version: 2.5
Name: relaybay
Version: 0.2.0
Summary: A live board and MCP server for coordinating many Claude Code sessions across projects.
Project-URL: Homepage, https://github.com/Codenator81/relaybay
Project-URL: Documentation, https://codenator81.github.io/relaybay/
Project-URL: Changelog, https://github.com/Codenator81/relaybay/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/Codenator81/relaybay/issues
Author: Aleksandrs Poltarjonoks
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: aiosqlite>=0.20
Requires-Dist: fastapi>=0.115
Requires-Dist: jinja2>=3.1
Requires-Dist: jsonschema>=4.20
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: mcp<3,>=2
Requires-Dist: platformdirs>=4.2
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: regex>=2024.11.6
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# relaybay

[![CI](https://github.com/Codenator81/relaybay/actions/workflows/ci.yml/badge.svg)](https://github.com/Codenator81/relaybay/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/relaybay)](https://pypi.org/project/relaybay/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Docs](https://github.com/Codenator81/relaybay/actions/workflows/docs.yml/badge.svg)](https://codenator81.github.io/relaybay/)

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: early (0.1).** relaybay is built for my own workflow first and changes quickly. Expect
> rough edges; issues and ideas are welcome.

![The relaybay board updating live while sessions report their work](https://raw.githubusercontent.com/Codenator81/relaybay/main/docs/assets/board.gif)

## Quick start

```bash
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>)
```

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](https://codenator81.github.io/relaybay/getting-started/install/) ·
[Install with your coding agent](https://codenator81.github.io/relaybay/getting-started/agent-install/).
Something off? `relaybay doctor`.

**Documentation:** [codenator81.github.io/relaybay](https://codenator81.github.io/relaybay/) ·
[Specification](docs/SPEC.md) (how it behaves now) · [Roadmap](docs/ROADMAP.md) ·
[Architecture](docs/architecture.md)

## Features

- **Board** — projects with per-stage counts; per project, columns `plan → dev → test → live → done`
  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. 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.
- **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 `done` column shows tasks closed in the last
  `done_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=…`). 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 = true` a 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 from `live` or `done`) 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, `Stop` reminds the agent (at most twice) until it acknowledges,
  and agents answer with `comment_add` (their replies land in your Inbox). An opt-in, experimental
  wake-up hook (`relaybay setup --apply --wake --force-wake`) wakes an idle session for a new
  comment.
- **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 is `read` by default), changed only by you on the board (agents
  propose with `environment_propose`). The `PreToolUse` hook 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 (Activity → Actions on live).
- **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 optional `policy.json` in 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 with `policy_propose`.
- **MCP server** — Streamable HTTP at `/mcp` in 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_patch` takes 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 a report before `test`, `progress` before `done`), a description template and
  free-text guidance. Global rules come from `config.toml`, a project can override them; agents read
  them through `rules_get` or `relaybay://rules/<project>`, and `project_snapshot` starts with the
  rules hash. A stage move that misses a rule succeeds with a warning (or is refused with
  `rules_mode = "strict"`), in MCP responses and on the board.
- **Local and private** — one process, SQLite, binds to `127.0.0.1`, token-protected, no telemetry,
  no outbound calls, no CDN.

## Try it with demo data

```bash
relaybay demo --home ./relaybay-demo                 # acme-shop and demo-api, tasks in every stage
relaybay serve --home ./relaybay-demo --port 8766
```

## Connect Claude Code

```bash
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](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)

```bash
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](docs/connect-claude-code.md#3-live-session-status-hooks).

### 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](docs/mcp-tools.md#schema-changes-and-long-running-sessions).
The tool reference is in [docs/mcp-tools.md](docs/mcp-tools.md).

## Configuration

Settings come from defaults, then `config.toml` in the data directory, then `RELAYBAY_*` environment
variables, then command-line flags.

| Setting | Default | Env | Flag |
|---|---|---|---|
| data directory | per-user data dir (`platformdirs`) | `RELAYBAY_HOME` | `--home` |
| bind address | `127.0.0.1` | `RELAYBAY_HOST` | `--host` |
| port | `8765` | `RELAYBAY_PORT` | `--port` |
| extra allowed Host names | none | `RELAYBAY_ALLOWED_HOSTS` (comma-separated) | — |
| desktop session link | `claude://claude.ai/epitaxy/{id}` | `RELAYBAY_DESKTOP_LINK_TEMPLATE` | — |
| days a done task stays in the done column | `7` | `RELAYBAY_DONE_WINDOW_DAYS` | — |
| keep done tasks without the tracker work log on the board | `false` | `RELAYBAY_REQUIRE_TRACKER_LOG` | — |
| what a stage move that misses a rule does: `warn` or `strict` | `warn` | `RELAYBAY_RULES_MODE` | — |
| `waiting_on` names that mean you (listed in the Inbox) | `owner`, `me`, `you` | `RELAYBAY_OWNER_NAMES` (comma-separated) | — |
| the global policy file ([policy reference](https://codenator81.github.io/relaybay/reference/policy/)) | `policy.json` in the data directory | `RELAYBAY_POLICY_FILE` | — |
| legacy: the guard mode (`off`, `log`, `warn`, `block`), a layer under the policy file | from the policy (`warn`) | `RELAYBAY_GUARD_MODE` | — |
| legacy: agents' level per environment kind (`[permission_defaults]`), a layer under the policy file | from the policy (local `full`, test `full`, live `read`) | — | — |
| folder with Claude Code's `.claude/` and `.claude.json` (setup, Integrations) | your home directory | `RELAYBAY_CLAUDE_HOME` | `--claude-home` |

The data directory holds `relaybay.sqlite`, the `token` file, the optional `config.toml` and
the optional `policy.json` (what agents may do; see
[Full access on a trusted local machine](https://codenator81.github.io/relaybay/how-to/trusted-machine/)
for an example):

```toml
port = 8765
allowed_hosts = ["my-laptop.lan"]   # needed only when you bind to a LAN address
desktop_link_template = "claude://claude.ai/epitaxy/{id}"  # {id} = desktop session id (local_…)
done_window_days = 7                # older done tasks are archived
require_tracker_log = false         # true: done tasks without the tracker work log stay and show "not logged"
owner_names = ["owner", "me"]       # waiting_on values listed in the Inbox
rules_mode = "warn"                 # "strict": a stage move that misses a rule is refused

[stages.labels]                     # display names; the stage keys stay plan/dev/test/live/done
dev = "in progress"
done = "shipped"

[reports.labels]                    # report badges: inspected/changed/verified/committed/pushed/blocked, S/M/L
verified = "checked"

[reports.hints]                     # badge tooltips
M = "medium change"

[rules]                             # global working rules, merged over the built-in defaults
guidance = "Ask the owner before anything goes live."
description_template = "Goal:\nWhy:\nDone when:"

[rules.report_format]               # states/sizes: a subset of the built-in ones
sizes = ["S", "M", "L"]

[rules.stage_requirements]          # per target stage; a list replaces the default, [] drops it
test = [{ kind = "report_since_stage_change" }]
done = [{ kind = "field_present", field = "progress" }]
```

A rules error in `config.toml` (unknown key, stage, rule kind or field) stops `relaybay serve`
with a message that names the key. A broken project override never stops the server: it is
logged, the project falls back to the global rules, and `rules_get` and `project_snapshot` say
"project override ignored: <error>". Project overrides and the merge rules are described in
[docs/mcp-tools.md](docs/mcp-tools.md#working-rules).

`relaybay token --rotate` creates a new token; restart the server and update the Claude Code entry.

### Troubleshooting: "token not valid"

Each data folder has its own token. `relaybay serve` prints the folder it uses (`Data folder: …`);
run `relaybay token` with the same `--home` (or `RELAYBAY_HOME`). `relaybay token` prints its folder
and warns when the server on the port uses a different token (another folder, or a rotation without
a restart). After `relaybay token --rotate`, restart the server. `relaybay doctor` checks this and
everything else in one command ([troubleshooting](https://codenator81.github.io/relaybay/how-to/troubleshooting/)).

## Roadmap

- **0.1.0** — board, MCP tools, working rules, hooks and `relaybay setup`, packaging
  (`uv tool install`, `uvx`, `pipx`, Docker), `relaybay doctor`, docs site, demo workspace.
- **0.2.0** — sidebar navigation and Inbox, comments to agents, project environments and access,
  policy as data.
- **0.3.0** — review checklist with screenshots, memory and documents.
- **Later** — annotations, map and usage, rules versioning, intake, agents started from relaybay.

Details and status: [docs/ROADMAP.md](docs/ROADMAP.md). Designs of upcoming steps are in
[docs/design/](docs/design/index.md), decisions in [docs/adr/](docs/adr/). relaybay sends no
telemetry.

## Contributing and feedback

- Questions, ideas, show and tell: [Discussions](https://github.com/Codenator81/relaybay/discussions).
- Bugs and feature requests: [issues](https://github.com/Codenator81/relaybay/issues/new/choose)
  (include `relaybay doctor` output for bugs).
- Security problems: report privately, see [SECURITY.md](SECURITY.md).
- Code: [CONTRIBUTING.md](CONTRIBUTING.md); AI coding tools: [AGENTS.md](AGENTS.md). Everyone
  follows the [Code of Conduct](CODE_OF_CONDUCT.md); how decisions are made:
  [GOVERNANCE.md](GOVERNANCE.md).

## License

[MIT](LICENSE)
