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