Agentrelay

AgentRelay

One project. Multiple AI agents. Zero repeated work.

Let AI continue where another AI stopped.

It tracks active sessions, task leases, advisory file ownership, decisions, failed attempts, Git state, and handoffs so Codex, Claude Code, and other agents can continue each other's work without rebuilding context from scratch. Its built-in tmux transport also lets those agents read and message trusted panes without installing a second MCP server.

> Not another chat memory. A local coordination layer for coding agents.

What works in v0.4.0

• Local-first SQLite storage inside a repository or workspace
• Fixed non-Git workspace boundaries with child-repository Git context
• MCP server with ten coordination tools and five live terminal tools
• Built-in tmux transport with no tmux-bridge-mcp runtime dependency
• One-session tmux boundary with pane labels and self-message prevention
• Redacted, size-limited terminal reads and single-line message sends
• Persistent read-before-send guards and content-free terminal audit events
• Agent sessions and heartbeats
• Expiring task leases
• Advisory file and glob claims with overlap warnings
• Structured development events and architecture decisions
• Potential decision-conflict detection
• FTS5 search across events, decisions, and handoffs
• Token-budgeted context packs
• Deterministic Git-aware Markdown handoffs
• CLI fallback for agents without lifecycle hooks
• Secret redaction and sensitive-path filtering
• No external model or hosted service required

The workflow

Agent A joins
  -> claims a task and file scope
  -> records decisions, tests, and failed attempts
  -> creates a Git-aware handoff and releases its leases

Agent B joins
  -> builds a task-specific context pack
  -> sees prior attempts, decisions, tasks, and file claims
  -> claims the continuation and starts from verified project state

Install

AgentRelay is not published to npm yet.

Install the current GitHub repository as one self-contained CLI and MCP server:

npm install -g github:arumwu/agentrelay
agentrelay --version

Or install from a source checkout:

git clone https://github.com/arumwu/agentrelay.git
cd agentrelay
npm install
npm run build
npm link

Node.js 22.13 or newer is required. The coordination and memory features work without tmux; the live terminal tools additionally require tmux 3.2 or newer.

Quick start

Run these commands from a Git repository, or pin AgentRelay to a larger workspace with --repo /absolute/path before the subcommand.

agentrelay --repo /workspaces/company init
agentrelay --repo /workspaces/company join \
  --agent codex-01 \
  --type codex \
  --cwd products/api \
  --task "Implement OAuth callback"

The join command returns a session UUID. Use it for claims and event records:

agentrelay claim-task \
  --session SESSION_UUID \
  --title "Implement OAuth callback" \
  --description "Validate callback and exchange tokens"

agentrelay claim-scope \
  --session SESSION_UUID \
  --pattern "src/auth/**"

agentrelay event \
  --session SESSION_UUID \
  --type attempt \
  --summary "Service account approach failed" \
  --content "Normal user OAuth requires authorization-code flow"

agentrelay context "Finish OAuth refresh flow" --cwd products/api --budget 5000

agentrelay handoff \
  --session SESSION_UUID \
  --title "OAuth implementation handoff"

Connect Codex

Configure AgentRelay in the actual Git repository where Codex starts. Create .codex/config.toml at that repository root:

[mcp_servers.agentrelay]
command = "agentrelay"
args = [
  "--repo",
  "/absolute/path/to/your/workspace",
  "serve"
]

Do not use a user-global codex mcp add unless you intentionally want every Codex session to start AgentRelay. Codex stops project-config discovery at the Git root, so a .codex/config.toml placed only in a parent multi-project workspace is not inherited when Codex starts directly inside a nested repository. Add the project config to each actual repository that should participate; all of them may still point to the same AgentRelay workspace boundary.

Connect Claude Code

Run this from each actual repository and use local scope so unrelated Claude Code sessions do not start AgentRelay:

claude mcp add --scope local agentrelay -- \
  agentrelay \
  --repo /absolute/path/to/your/workspace \
  serve

AgentRelay advertises its lifecycle instructions through MCP initialization. For clients that do not consume server instructions, place the fallback rules from [examples/AGENTS.md](examples/AGENTS.md) in the repository's AGENTS.md or CLAUDE.md.

Live tmux transport

AgentRelay includes the terminal transport directly. Installing @arumwu/agentrelay or the GitHub package is enough; do not install or register a separate tmux-bridge-mcp server.

Run the agents you want to coordinate in one tmux session. When AgentRelay starts inside tmux it automatically restricts terminal access to that current session:

agentrelay terminal list
agentrelay terminal name %3 codex
agentrelay terminal read codex --lines 40
agentrelay terminal send codex "Review src/auth.ts and report any regressions"

terminal read opens a 90-second, one-use guard for that actor and pane. After one send, read the pane again before sending another message. AgentRelay stores audit metadata such as the pane, byte count, and correlation ID, but never persists captured terminal output or message content.

If AgentRelay starts outside tmux, explicitly allow one session:

agentrelay terminal --tmux-session agent-work list

For MCP clients launched outside tmux, set AGENTRELAY_TMUX_SESSION in that server's environment. Set AGENTRELAY_TMUX_SOCKET only when using a non-default socket. Terminal targets outside the selected session are rejected.

terminal_send types one literal, single-line message followed by Enter. A shell pane can interpret that text as a command, so only label and target panes you trust. AgentRelay intentionally exposes no arbitrary key or generic shell-execution tool.

Workspace mode

A workspace may contain many independent Git repositories and non-Git projects:

/workspaces/company/             <- fixed AgentRelay boundary
├── .agentrelay/                 <- shared workspace memory
├── products/api/.git/
├── products/web/.git/
└── research-notes/

The MCP server remains fixed to /workspaces/company. Each agent_join and build_context call may include working_directory, such as products/api. AgentRelay rejects directories outside the fixed workspace and obtains Git status from the child repository containing that working directory.

Task and scope claims remain workspace-wide. In the example above, claim products/api/src/**, not only src/**, to avoid ambiguity between child projects.

MCP tools

| Tool | Purpose | |---|---| | project_init | Initialize or inspect workspace-local storage and its fixed boundary | | agent_join | Register an agent session and its current workspace directory | | agent_status | Read coordination state and optionally heartbeat a session | | claim_task | Create or claim an expiring task lease | | claim_scope | Claim workspace-relative files or globs and receive overlap warnings | | record_event | Record an attempt, result, issue, discovery, test, note, or completion | | record_decision | Record a structured decision and identify potential conflicts | | search_memory | Search events, decisions, and handoffs with SQLite FTS5 | | build_context | Compile task-specific Git, coordination, and memory context | | create_handoff | Generate a Markdown handoff and optionally release leases | | terminal_list | List panes only in the allowed tmux session | | terminal_read | Read redacted, capped pane output and open a one-use send guard | | terminal_send | Send one literal single-line message and Enter after a recent read | | terminal_name | Assign an AgentRelay-specific pane label | | terminal_doctor | Diagnose tmux binary, socket, session, and safety limits |

Local data

Each coordinated repository or workspace owns its memory:

.agentrelay/
├── agentrelay.db
├── events.jsonl
└── handoffs/
    └── 2026-...-handoff.md

.agentrelay/ is excluded from this repository's Git history by default. In a non-Git workspace it remains a hidden local directory. A team may choose to version redacted handoff exports, but the database should normally remain local.

Existing installations are migrated automatically to the .agentrelay/agentrelay.db storage layout on first startup.

Coordination semantics

Task leases are exclusive while active. If a second agent requests the same task, AgentRelay returns a conflict with the current owner and expiry.

Scope claims are advisory. AgentRelay warns when file or glob patterns may overlap, but it does not pretend it can prevent an agent from editing files outside MCP. Agents and hooks should treat warnings as a coordination stop.

Decision conflicts are also advisory. AgentRelay flags related active decisions based on task, title, and scope overlap; a human or agent must explicitly supersede the old decision.

Security boundaries

• The workspace root is resolved once when the server starts.
• Agent working directories must exist inside that fixed workspace.
• MCP tools cannot escape to another workspace path.
• AgentRelay does not expose a generic shell, arbitrary-key, or test-command tool.
• Terminal access is limited to the current or explicitly configured tmux session.
• Terminal sends require a recent read, reject self-targeting, and accept only one literal line.
• Terminal output is redacted and size-limited; captured output and message text are not persisted.
• Sending to a shell pane may still execute text, so terminal access is only for trusted panes.
• Git inspection uses fixed argument arrays without a shell.
• .env, private keys, and credential-like paths are filtered.
• Common API keys, tokens, passwords, cookies, and bearer headers are redacted before storage.
• Agent-authored memory remains evidence-linked context, not trusted executable instructions.

See [SECURITY.md](SECURITY.md) for reporting and threat-model details.

Development

npm install
npm run check

The integration tests create temporary Git repositories and exercise task conflict, scope overlap, memory search, decision conflict, handoff generation, and a real in-memory MCP client/server handshake. When tmux is installed, they also create an isolated socket and verify real pane listing, labeling, read-before-send enforcement, messaging, self-target rejection, and cross-session isolation. CI always installs tmux and runs this path.

Roadmap

• Agent-specific hooks for automatic lifecycle capture
• Git post-commit/post-merge adapters
• Task completion and blocked-state commands
• Optional semantic retrieval and reranking
• Portable redacted exports and repository sync
• GitHub issue and pull-request projections
• A small coordination dashboard

License

AgentRelay is licensed under Apache License 2.0. See [LICENSE](LICENSE). The built-in terminal transport includes work adapted from MIT-declared tmux-bridge-mcp; see [THIRDPARTYNOTICES.md](THIRDPARTYNOTICES.md) and [LICENSES/tmux-bridge-mcp-MIT.txt](LICENSES/tmux-bridge-mcp-MIT.txt).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arumwu
• Source: arumwu/agentrelay
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.