npm package: @rajdevxd/agentrelay
Description: Switch coding agents without losing context. Generate handoff prompts across Claude Code, Codex, and OpenCode.
Author: Nishant Gaurav
Latest version: 2.0.7

# AgentRelay

[![npm version](https://img.shields.io/npm/v/@rajdevxd/agentrelay.svg)](https://www.npmjs.com/package/@rajdevxd/agentrelay)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

AgentRelay helps you switch coding agents without losing momentum.

It reads your current AI session, captures real project state (including git context), and generates a high-quality continuation prompt so the next agent can continue from where you actually stopped.

## Problem

When you switch agents mid-task, context usually breaks.

- Important decisions are scattered in chat history
- Errors and failed attempts get repeated
- The next agent starts from an incomplete picture

## Solution

AgentRelay builds a clean handoff prompt from:

- Session messages
- Tool calls and outputs
- Open errors and failed approaches
- Current git state and changed files

Result: faster context transfer, less repetition, better continuity.

## Supported Sources

- Claude Code
- Codex
- OpenCode

## Supported Targets

- generic
- claude
- codex
- cursor
- chatgpt

## Features

- Smart latest-session detection for the current project
- Focused context extraction with noise reduction
- Error-aware prompt generation
- Git-aware summaries (status, diffs, untracked files)
- Optional prompt refinement via OpenRouter
- Clipboard copy on macOS, Linux, and Windows
- Built-in diagnostics with doctor command
- Session browsing with sessions command

## Install

Run once with npx:

```bash
npx @rajdevxd/agentrelay
```

Install globally:

```bash
npm i -g agentrelay
```

## Quick Start

```bash
cd your-project
agentrelay
```

You will:

1. Pick source agent (if not provided)
2. Parse latest session for current repo
3. Capture git/project context
4. Generate continuation prompt
5. Copy output to clipboard

## Usage

```bash
# Basic
agentrelay

# Choose source
agentrelay --source claude
agentrelay --source codex
agentrelay --source opencode

# Choose target style
agentrelay --source claude --target codex

# Use exact session
agentrelay --source codex --session <id-or-path>

# Save output to file
agentrelay --output ./handoff.md

# Refine with OpenRouter
agentrelay --refine

# Pick preserved context start interactively
agentrelay --pick-user

# Start preserved context from nth user prompt
agentrelay --from-user 2

# Diagnostics
agentrelay doctor --source claude

# List sessions
agentrelay sessions --source codex --limit 5
```

## Commands

- continue (default): generate handoff prompt
- doctor: validate environment, source availability, git, clipboard, and API key state
- sessions: list recent sessions for current project

## Flags

| Flag | Description |
| --- | --- |
| --source <name> | Source agent: claude, codex, opencode |
| --target <name> | Target format: generic, claude, codex, cursor, chatgpt |
| --session <id\|path> | Use specific session |
| --pick-user | Pick starting user message interactively |
| --from-user <n> | Start preserved context from nth user message |
| --output, -o <file> | Write final prompt to file |
| --refine | Refine prompt with provider |
| --provider <name> | Refinement provider (default: openrouter) |
| --model <name> | Override model |
| --api-key <key> | Override provider API key |
| --limit, -n <count> | Session rows limit for sessions command |
| --help, -h | Show help |
| --version, -v | Show version |

## LLM Refinement

Refinement is optional.

- Provider: openrouter
- API key resolution order: CLI flag, env variable, local config

Environment variable:

```bash
OPENROUTER_API_KEY=your_key_here
```

Local config file path:

```text
~/.agentrelay.json
```

## Session Storage Paths

| Source | Path | Format |
| --- | --- | --- |
| Claude Code | ~/.claude/projects/<encoded-cwd>/*.jsonl | JSONL |
| Codex | ~/.codex/sessions/<year>/<month>/<day>/*.jsonl | JSONL |
| OpenCode | ~/.local/share/opencode/opencode.db | SQLite |

## Requirements

- Node.js 18+
- One supported source agent with existing session data
- sqlite3 CLI only for OpenCode source
- Git repository recommended for best code-state capture

## Troubleshooting

- No sessions found:
	- Run source agent once in the current project
	- Run agentrelay sessions --source <name>
	- Run agentrelay doctor --source <name>
- OpenCode parsing issues:
	- Ensure sqlite3 CLI is available
- Refinement failed:
	- Check OPENROUTER_API_KEY
	- Retry without --refine to use raw mode

## Maintainer

- GitHub: https://github.com/codewithevilxd
- Portfolio: https://nishantdev.space
- Email: codewithevilxd@gmail.com

## License

MIT