Relay

Git for AI sessions — sync the reasoning behind your code across editors, machines, and teammates. Encrypted, local-first, and built for real workflows.

The problem

When you code with an AI assistant (Cursor, VS Code Copilot, OpenCode, Antigravity, etc.), you build valuable context over hours:

Architectural decisions and trade-offs
Why you chose approach A over B
Files you touched and errors you hit
The current mental model of the problem

That context lives in proprietary, local storage inside each editor. It does not travel with your Git repo.

So when you:

Open a new chat because the context window is full
Switch machines or hand off to a teammate
Move to a different editor

…you lose the thread. Your repo has the code; nobody has the conversation that produced it.

What Relay does

Relay is a CLI that:

Reads AI chat sessions from supported editors on your machine
Normalizes them into a standard JSON format
Encrypts them with age + your team's SSH keys
Stores them under .ai-memory/ in your project
Generates .ai-memory/HANDOFF.md — a human- and agent-friendly briefing for the next session

You commit handoff + config to Git. Your teammate runs git pull, reads HANDOFF.md, and continues where you left off.

Editors → readers → standard session JSON → age encrypt → .ai-memory/ → Git → HANDOFF.md

Relay is not…

Relay is not	Relay is
A bigger context window inside one editor	A save/load checkpoint for AI sessions
A replacement for `context.md` / `AGENTS.md`	A session log that complements static project docs
A hosted chat server	Local-first + Git + optional team encryption
Import into every editor's native sidebar	@file handoff where APIs don't exist (Antigravity, Cursor import)

context.md describes how the project works (stable, curated).
Relay captures what you and the AI decided in this session (dynamic, exported from the editor).

Two modes

Mode A — Team relay (primary)

Share state with your team through Git.

relay sync --handoff
git add .ai-memory/HANDOFF.md .ai-memory/config.json .ai-memory/recipients.txt
git commit -m "chore: AI handoff"
git push

Teammate:

git pull
cat .ai-memory/HANDOFF.md
# full transcript (encrypted):
relay decrypt .ai-memory/sessions/session-*.json.age

Mode B — Editor bridge (secondary)

Continue the same conversation in another editor without starting from zero.

relay inject cursor antigravity   # prints @path to session.md
relay inject cursor vscode        # exports to .ai-memory/vscode-import/
relay inject vscode cursor

Supported editors

Editor	Read sessions	Inject into
Cursor	`~/.cursor/projects/<project>/agent-transcripts/*.jsonl`	`@.ai-memory/cursor-import/...`
VS Code (Copilot Chat)	`workspaceStorage/<hash>/chatSessions/` (`.json` / `.jsonl`)	`@.ai-memory/vscode-import/...`
OpenCode	`~/.local/share/opencode/`	Native session history
Antigravity	`~/.gemini/antigravity/brain/`	`@~/.gemini/.../session.md`

VS Code: open the repo in VS Code and use Copilot Chat so sessions are written to disk.
Antigravity: imported sessions do not appear in the sidebar; use @path in chat (official flow).

The contextvc binary alias is kept for backward compatibility.

Install

Requirements: Node 18+, pnpm (Corepack: corepack enable), age, Git.

Full guide: docs/INSTALL.md (registry, Git-only, security).

Global CLI (recommended)

Pin a version you trust:

corepack enable
pnpm setup && source ~/.zshrc   # once, if pnpm link --global fails
pnpm add -g @ticoxz/relay@1.3.1
relay --version

From Git (no `pnpm add -g`)

git clone https://github.com/ticoxz/Relay.git && cd Relay
corepack enable
pnpm install --frozen-lockfile
pnpm run build
pnpm link --global

Supply-chain note

pnpm installs from the npm registry (@ticoxz/relay). After recent npm attacks, prefer pinned versions or build from Git above. This repo uses pnpm-lock.yaml and CI runs pnpm install --frozen-lockfile.

Quickstart

cd your-project && git init
relay init
relay doctor          # optional: verify age, config, readers
# work with Cursor, VS Code, OpenCode, or Antigravity…
relay sync --handoff
git add .ai-memory/HANDOFF.md .ai-memory/HANDOFF.json .ai-memory/config.json .ai-memory/recipients.txt
git commit -m "chore: AI handoff"

By default, sync imports only the latest session per editor for this repo (fast). OpenCode/Cursor are filtered by project path so personal and work repos do not mix. Use relay sync --all for full history.

Context window full? (primary flow)

When the chat is ~90% full, save game and load game in a new chat:

relay sync --handoff
relay handoff --for-agent   # prints copy-paste prompt

Open a New Chat in your editor and send:

@.ai-memory/HANDOFF.md

Read the handoff and explain where we left off. Do not run commands or edit files until I ask.

Without those instructions, some agents treat "next steps" as tasks and start executing. HANDOFF.md and HANDOFF.json include do_not_execute guardrails for agents.

Run relay doctor if handoff feels stale or sync fails.

Commands

Command	Description
`relay init`	Wizard: encryption, summarizer, `.ai-memory/`
`relay sync [--handoff]`	Export latest session per editor → repo
`relay sync --all`	Export full history (slower)
`relay handoff [--for-agent]`	Regenerate `HANDOFF.md` + `HANDOFF.json`; `--for-agent` prints chat prompt
`relay doctor`	Validate age, config, readers, HANDOFF freshness
`relay-mcp`	MCP server (optional): `get_handoff`, `get_handoff_json`, `list_sessions`, `decrypt_session`
`relay inject <src> <dst>`	Bridge: `cursor` \| `vscode` \| `opencode` \| `antigravity`
`relay pull [editor]`	Pull one or all editors into `.ai-memory/sessions/`
`relay status [--editor] [--sessions]`	Dashboard
`relay install-hooks`	`pre-commit` sync + `post-checkout` / `post-merge`
`relay team auto-add`	Add SSH keys as age recipients
`relay decrypt <file.age>`	Decrypt a session file

Relay for agents (optional)

MCP and HANDOFF.json are for power users and CI. Start with @HANDOFF.md in a new chat; add MCP only if you need programmatic access.

Relay is a checkpoint between agent runs — not a code index (see tools like CodeGraph for that).

Artifact	Consumer
`AGENTS.md` / rules	How to work in this repo (stable)
`HANDOFF.md`	Human-readable session state
`HANDOFF.json`	Machine-readable schema v1 (`schema/HANDOFF.schema.json`)

HANDOFF.json includes agent_instructions.do_not_execute: true so agents explain context first instead of auto-running tasks.

MCP server (`relay-mcp`)

See docs/MCP.md for setup, optional rules, and the 90-day adoption review.

Add to Cursor → Settings → MCP:

{
  "mcpServers": {
    "relay": {
      "command": "relay-mcp",
      "args": [],
      "env": {
        "RELAY_PROJECT_ROOT": "/absolute/path/to/your/repo"
      }
    }
  }
}

Tools:

Tool	Purpose
`get_handoff`	`HANDOFF.md` + agent instructions
`get_handoff_json`	Structured v1 document
`list_sessions`	Metadata for `.ai-memory/sessions/*`
`decrypt_session`	Decrypt one `.age` file (local age + SSH)
`sync_status`	Whether handoff files exist

Prompt for a new chat

relay handoff --for-agent

Copy the output into a new chat, or use:

@.ai-memory/HANDOFF.md

Read the handoff and explain where we left off. Do not run commands or edit files until I ask.

GitHub Action (PR comments)

When a PR changes HANDOFF.md, post a short excerpt on the PR:

# .github/workflows/relay-handoff.yml
on:
  pull_request:
    paths: ['.ai-memory/HANDOFF.md', '.ai-memory/HANDOFF.json']
permissions:
  pull-requests: write
jobs:
  handoff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: ticoxz/Relay/action@v1.3.1

See action/action.yml. Comments only run when HANDOFF.md changed in the PR.

Agent role templates (prompts)

Onboarding (new teammate or new chat):

@.ai-memory/HANDOFF.md
@AGENTS.md

You are onboarding to this repo. Read HANDOFF for session context and AGENTS.md for rules.
Explain the project state and suggest a 30-minute plan. Do not edit files or run commands until I confirm.

Reviewer (before merge):

@.ai-memory/HANDOFF.json

Compare the PR diff with handoff decisions. List any contradictions or missing updates to HANDOFF.
Do not approve or run CI — checklist only.

Security

Sessions are encrypted with age using team SSH public keys (recipients.txt).
Raw chat files under .ai-memory/sessions/ are typically gitignored; you commit HANDOFF.md + config.
Only people with repo access and a listed SSH key can decrypt.

Development

This repo is pnpm-only (packageManager in package.json; npm install is blocked).

corepack enable
pnpm install --frozen-lockfile
pnpm run build && pnpm test
pnpm link --global

Publish (maintainers, 2FA on npm):

pnpm login
pnpm publish --access public

Tags v* trigger .github/workflows/publish.yml when NPM_TOKEN is set in repo secrets.

License

MIT — ticoxz/Relay

Name		Name	Last commit message	Last commit date
Latest commit History 19 Commits
.ai-memory		.ai-memory
.github		.github
action		action
docs		docs
schema		schema
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
.npmrc		.npmrc
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
RELEASE_v1.3.0.md		RELEASE_v1.3.0.md
doc.md		doc.md
jest.config.js		jest.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Relay

The problem

What Relay does

Relay is not…

Two modes

Mode A — Team relay (primary)

Mode B — Editor bridge (secondary)

Supported editors

Install

Global CLI (recommended)

From Git (no `pnpm add -g`)

Supply-chain note

Quickstart

Context window full? (primary flow)

Commands

Relay for agents (optional)

MCP server (`relay-mcp`)

Prompt for a new chat

GitHub Action (PR comments)

Agent role templates (prompts)

Security

Development

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Relay

The problem

What Relay does

Relay is not…

Two modes

Mode A — Team relay (primary)

Mode B — Editor bridge (secondary)

Supported editors

Install

Global CLI (recommended)

From Git (no pnpm add -g)

Supply-chain note

Quickstart

Context window full? (primary flow)

Commands

Relay for agents (optional)

MCP server (relay-mcp)

Prompt for a new chat

GitHub Action (PR comments)

Agent role templates (prompts)

Security

Development

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

From Git (no `pnpm add -g`)

MCP server (`relay-mcp`)

Packages