session-relay-mcp

Pass the baton between AI coding agents. session-relay-mcp reads the session stores that Codex, Claude Code, Antigravity, OpenCode, Freebuff and Grok already keep on your machine and turns them into inspectable history plus a one-call handoff brief — no cloud service and no copy-pasting context between agents.

Why

Every harness writes its own private session format. When one agent gets stuck, the next one starts blind: what was the goal, which files changed, what failed? This MCP server answers those questions from local files, so an operator or a different agent can resume the work immediately.

• Cross-harness — one interface over six local stores.

• Strictly read-only — SQLite is opened mode=ro with query_only, JSONL and JSON are only read. Stores are fingerprinted in tests to prove nothing is written.

• Baton-pass brief — handoff_context returns Goal, Files touched, Last observed state, Blocker and Suggested next steps as markdown.

• Bounded — giant Freebuff chats (hundreds of MB) are read from a capped tail; search has a byte budget.

Related MCP server: ai-r

Supported harnesses

Missing or empty stores return friendly empty states with warnings instead of errors.

Install

pipx install .
# or
uv tool install .
# or a plain virtual environment
python3 -m venv .venv && .venv/bin/pip install .

Installing exposes the session-relay console script; python3 -m session_relay.server works without it.

MCP client setup

The server speaks MCP over stdio and needs no arguments.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "session-relay": { "command": "session-relay", "args": [] }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.session-relay]
command = "session-relay"
args = []

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "session-relay": { "command": "session-relay", "args": [] }
  }
}

Antigravity (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "session-relay": { "command": "session-relay", "args": [] }
  }
}

OrquestraAI (~/.orquestra/mcps.json):

"session-relay": {
  "id": "session-relay",
  "name": "Session Relay (Cross-Harness)",
  "description": "Read-only cross-harness session inspection and handoff briefs.",
  "command": "session-relay",
  "args": [],
  "env": {},
  "globalEnabled": true,
  "enabledHarnesses": []
}

Tools

Harness ids: codex, claude, antigravity, opencode, freebuff, grok (aliases: claude-code, gemini, manicode, open-code, xai).

Example workflow

list_recent_sessions(limit=5)
inspect_session(harness="codex", session_id="latest", max_turns=3)
handoff_context(source_harness="codex")
search_sessions_history(query="deploy", harness="claude")

Configuration

No configuration is required for normal use.

Known limits

• Freebuff chats over 16 MB expose only their last 12 MB; turn counts above 4 MB fall back to the chat's recorded message count.

• Grok's local index contains prompts, not assistant or tool events, so its briefs are goal-focused.

• Codex search scans item text in a large database; expect a few hundred milliseconds on very large histories.

Development

python3 -m venv .venv
.venv/bin/pip install -e . pytest
.venv/bin/python -m pytest tests/ -q
bash scripts/check-file-size.sh

License

MIT — see LICENSE.