context-relay

context-relay

MCP server for AI agent session handoffs, enabling seamless context transfer 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. Sessions are stored in local SQLite by default (~/.context-relay/sessions.db), or in S3 to share sessions across team members, devices, or production agents. Multiple agents can read and write safely at the same time.

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, Codex), setup also installs a relaying-context skill. If you later uncheck an agent, setup removes both the MCP config and the managed skill.

Manual Configuration

If you prefer to configure agents manually, add context-relay to your MCP server config:

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").

Storage

By default, sessions are stored in local SQLite at ~/.context-relay/sessions.db — great for individual use on a single machine.

Switch to S3 when you need shared access: team members can hand off sessions to each other across devices, or production agents can read and write context from a central store.

Configuring with setup

npx context-relay setup

The setup wizard lets you pick a storage backend (SQLite, AWS S3, or S3-compatible) and walks you through bucket selection, credentials, and region. Config is saved to ~/.context-relay/config.json.

Configuring with environment variables

You can skip setup and configure storage entirely via environment variables in your MCP server config. This is useful when you want to set things up directly or share a config across machines.

Variable	Description	Default
CONTEXT_RELAY_BACKEND	"sqlite" or "s3"	"sqlite"
CONTEXT_RELAY_S3_BUCKET	S3 bucket name (required for S3)	—
CONTEXT_RELAY_S3_REGION	AWS region	"auto"
CONTEXT_RELAY_S3_ENDPOINT	Custom endpoint (for R2, MinIO, Tigris, etc.)	—
CONTEXT_RELAY_S3_ACCESS_KEY_ID	Access key ID (falls back to AWS_ACCESS_KEY_ID)	—
CONTEXT_RELAY_S3_SECRET_ACCESS_KEY	Secret access key (falls back to AWS_SECRET_ACCESS_KEY)	—
CONTEXT_RELAY_S3_PROFILE	AWS profile name	—
CONTEXT_RELAY_S3_PREFIX	Key prefix for S3 objects	""
CONTEXT_RELAY_S3_FORCE_PATH_STYLE	"true" for path-style URLs (MinIO, etc.)	"false"

Example: AWS S3 with a profile

{
  "mcpServers": {
    "context-relay": {
      "command": "npx",
      "args": ["-y", "context-relay"],
      "env": {
        "CONTEXT_RELAY_BACKEND": "s3",
        "CONTEXT_RELAY_S3_BUCKET": "my-relay-sessions",
        "CONTEXT_RELAY_S3_REGION": "us-west-2",
        "CONTEXT_RELAY_S3_PROFILE": "my-profile"
      }
    }
  }
}

Example: Cloudflare R2

{
  "mcpServers": {
    "context-relay": {
      "command": "npx",
      "args": ["-y", "context-relay"],
      "env": {
        "CONTEXT_RELAY_BACKEND": "s3",
        "CONTEXT_RELAY_S3_BUCKET": "my-relay-sessions",
        "CONTEXT_RELAY_S3_ENDPOINT": "https://<account-id>.r2.cloudflarestorage.com",
        "CONTEXT_RELAY_S3_ACCESS_KEY_ID": "your-r2-access-key",
        "CONTEXT_RELAY_S3_SECRET_ACCESS_KEY": "your-r2-secret-key"
      }
    }
  }
}

Environment variables take priority over ~/.context-relay/config.json, so you can use both — e.g. run setup for defaults and override specific values per-agent with env vars.

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)

Examples

Saving a session

Just ask your agent to save your work:

"Save this session to the relay so I can pick it up in Cursor."

Or use the skill directly — /relaying-context in Claude Code, $relaying-context in Codex.

The agent captures your full context and returns a session ID like flying-coyote-xb2n.

Resuming by description

You don't need to remember the session ID. Just describe what you were working on:

"Pull up the session where I was refactoring the auth middleware."

The agent searches sessions by keyword and loads the matching context.

Resuming by time

"Load my most recent session."

"What was I working on yesterday?"

The agent lists sessions sorted by last update and picks the right one.

Resuming by ID

If you have the ID:

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

Updating an existing session

"Update the relay session with the current progress."

The agent saves a new version to the same session ID, preserving the full revision history.

Browsing from the CLI

# List recent sessions
context-relay sessions

# Search by keyword
context-relay sessions "auth middleware"

# View a specific session
context-relay get flying-coyote-xb2n