context-relay

context-relay

MCP server that stores AI agent sessions locally in SQLite, enabling seamless handoffs between coding agents (Claude Code, Cursor, Windsurf, Codex, etc.).

Start work in one agent, save a detailed context summary, then continue in a different agent with full context.

How it works

Each agent spawns its own context-relay STDIO process. All processes read/write the same SQLite database at ~/.context-relay/sessions.db (WAL mode for safe concurrency).

Sessions are mutable — multiple agents can update the same session over time. Each save creates a new version (revision history), retrievable by session ID (latest) or specific version number.

Session IDs are human-readable: adjective-noun-xxxx (e.g., flying-coyote-xb2n).

Quick Start

npx context-relay setup

This detects your installed agents and configures them automatically:

  context-relay setup

  Select agents to configure (space to toggle, enter to confirm):

  [x] Claude Code    ~/.claude.json
  [x] Cursor         ~/.cursor/mcp.json
  [ ] Windsurf       (not detected)
  [x] Codex          ~/.codex/config.toml

Restart your agents after setup to pick up context-relay.

For agents with skill support (Claude Code, Cursor, Codex), setup also installs a managed context-relay skill so agents can call handoff workflows more reliably. If you later uncheck an agent, setup removes the MCP config and any managed context-relay skill for that agent.

Manual Configuration

If you prefer to configure agents manually:

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "context-relay": {
      "command": "npx",
      "args": ["-y", "context-relay"]
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "context-relay": {
      "command": "npx",
      "args": ["-y", "context-relay"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "context-relay": {
      "command": "npx",
      "args": ["-y", "context-relay"]
    }
  }
}

Codex

Add to ~/.codex/config.toml:

[mcp_servers.context-relay]
command = "npx"
args = ["-y", "context-relay"]

Skills

context-relay setup installs a relaying-context skill for agents that support it. The skill teaches agents how to save detailed context summaries for handoff — it is managed automatically (installed when you select an agent, removed when you deselect).

Agent	Skill path	Invoke with
Claude Code	~/.claude/skills/relaying-context/SKILL.md	/relaying-context
Codex	~/.agents/skills/relaying-context/SKILL.md	$relaying-context

Both agents also support implicit invocation — the skill triggers automatically when your request matches (e.g. "save this session for handoff").

Tools

save_session

Save or update an agent session context.

Parameters:

Name	Type	Required	Description
id	string	No	Session ID to update. Omit to create new.
title	string	Yes (create)	Short descriptive title
context	string	Yes	Detailed context summary
agent	string	Yes	Agent identifier (e.g. "claude-code")
project	string	No	Project directory path

list_sessions

List or search saved sessions.

Parameters:

Name	Type	Required	Description
query	string	No	Full-text search query
project	string	No	Filter by project path
agent	string	No	Filter by latest agent
limit	number	No	Max results (default 20)
offset	number	No	Pagination offset

get_session

Retrieve a session by ID with full context and version history.

Parameters:

Name	Type	Required	Description
id	string	Yes	Session ID
version	number	No	Specific version (default: latest)

Example Handoff Workflow

In Claude Code — finish a work session:

"Save the current session context so I can continue in Cursor."

The agent calls save_session and returns a session ID like flying-coyote-xb2n.

In Cursor — pick up where you left off:

"Load session flying-coyote-xb2n and continue the work."

The agent calls get_session and gets the full context, then continues working.

Back in Claude Code — check progress:

"List my recent sessions"

The agent calls list_sessions to show all sessions sorted by last update.