npm package: @rk0429/agentic-relay
Description: Unified MCP relay for Claude Code, Codex CLI, and Gemini CLI
Author: RK0429
Latest version: 21.0.0

# agentic-relay

`agentic-relay` is a TypeScript MCP server that launches Claude Code, Codex CLI,
and Gemini CLI through a single MCP endpoint. It now exposes both agent
execution tools, Phase 2 task management tools, Phase 3 task-type routing, and
Phase 4 visualization commands.

## Current scope

- Phase 1 foundation from `docs/requirements.md`
- Phase 2 task management from `docs/requirements.md`
- Phase 3 task-type routing from `docs/requirements.md`
- Phase 4 visualization UI from `docs/requirements.md`
- Phase 5 unified relay CLI from `docs/requirements.md`
- `relay mcp serve` over stdio
- `relay visualize` for a colorized task tree and active-agent dashboard
- `relay [backend] [--resume <session_id>] [-p <prompt>]` for interactive and non-interactive backend access
- VSCode Explorer views for task trees and active agents with `fs.watch` refresh
- Parallel `spawn_agents`
- Backend routing, depth guard, response persistence, and session metadata
- Automatic cross-backend handoff when `session_id` is resumed with a different backend
- Task CRUD, status transitions, dependency resolution, review flow, and `spawn_agents`/`agents[].task_id` linkage
- Task write permissions scoped to the assigned task subtree, while reads remain open
- Task warnings for missing `acceptance_criteria`, with leaf tasks blocked from execution until criteria are defined
- `task_type`-based backend auto-selection and orchestration-only re-delegation

## Usage

```bash
pnpm install
pnpm build
pnpm relay
pnpm relay codex
pnpm relay claude -p "hello"
pnpm relay claude --resume <session_id>
pnpm relay mcp serve
pnpm relay visualize
```

Responses are stored under `.relay/` in the current working directory.

`relay` chooses the default backend in `claude -> codex -> gemini` order when
no backend is specified. Interactive mode runs an Ink-based relay shell that
shows the available backends and keeps one relay-managed session per backend.
Use `Ctrl+B` to cycle the active backend and `Ctrl+C` to exit. When you switch
to a backend that has no current session yet, relay starts it with a
cross-backend handoff from the most recent backend response. Prompt mode
(`-p/--prompt`) uses the same relay-managed session persistence, so Claude and
Codex sessions can later be resumed with `--resume <session_id>`. Gemini
follows the documented constraint and rejects `-p` together with `--resume`.

`relay visualize` renders:

- A colorized task tree with task ID, title, status, assigned agent, and dependencies
- Blocked tasks with an inline cause derived from unresolved dependencies or task comments
- An active-agent list with agent ID, task, backend, and elapsed runtime

When the package is loaded as a VSCode extension, it contributes two Explorer
views:

- `Agentic Relay Tasks` for the task tree
- `Agentic Relay Agents` for active delegations

The extension refreshes those views automatically when `.relay/tasks/*.json` or
`.relay/logs/*.jsonl` change. A manual `Agentic Relay: Refresh Views` command is
also contributed.

## MCP Tools

- `spawn_agents`
- `create_task`
- `transition_task`
- `assign_agent`
- `list_tasks`
- `get_task`
- `update_task`
- `archive_task`

Task operations are read-open by default. Mutations are limited to the current
agent's assigned subtree (plus bootstrap operations on tasks the agent created),
and task payloads include `warnings` when `acceptance_criteria` is missing.
Leaf tasks cannot transition to `ready` or `in_progress` until their
`acceptance_criteria` is defined.
`list_tasks` and the task-tree views hide `done`, `archived`, and
`superseded` tasks by default; use an explicit `status` filter when you need to
inspect terminal tasks.

`spawn_agents` links task automation through `agents[].task_id`. When a given
agent entry includes `task_id`, only that task is auto-transitioned and
auto-assigned from the spawned session.

`spawn_agents` normally resolves `backend` from `task_type`. Use `backend` only
as an exceptional override when you intentionally need a non-default backend;
requests that merely repeat the default route are rejected as redundant. The
default routing is `orchestration/document_writing/code_review -> claude` and
`research/document_review/code_writing -> codex`, with fallback to another
installed backend if the preferred one is unavailable. Only
`task_type="orchestration"` child agents receive `spawn_agents`; all other
task types are treated as leaf agents.

Routing can be customized through `.relay/config.json`:

```json
{
  "max_depth": 5,
  "routing": {
    "research": "gemini",
    "code_writing": "claude"
  },
  "task_retention_days": {
    "done": 30,
    "archived": 7
  }
}
```

`max_depth` sets the default call-depth limit when `spawn_agents.max_depth` is
omitted. When a `routing` entry exists for a `task_type`, it overrides the
built-in default for backend auto-selection. `task_retention_days` prunes
expired `done` / `archived` leaf tasks during subsequent task reads; terminal
tasks with children or dependants are retained until they become isolated.

For Codex-backed leaf agents, relay also applies a narrow bootstrap guard:
sibling Codex launches are slightly staggered, and if a child emits
`thread.started` but never materializes its local state bootstrap, relay writes
diagnostics under `.relay/diagnostics/<session>/attempt-N/`, terminates the
stalled child, and retries once for read-only task types (`research`,
`document_review`, `code_review`).

Persisted relay files are created with private permissions (`0600`), and a
repeatable non-functional benchmark can be run with:

```bash
pnpm benchmark:nf
```

To stress-test Codex bootstrap behavior and collect per-run artifacts under
`./tmp`, run:

```bash
pnpm stress:codex-bootstrap -- --count 20 --concurrency 4
```

## Use From This Workspace

This workspace is configured to consume the published package via
`@rk0429/agentic-relay@latest`.

### Claude Code

Project MCP registration lives in `.mcp.json`:

```json
{
  "mcpServers": {
    "agentic-relay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@rk0429/agentic-relay@latest", "mcp", "serve"]
    }
  }
}
```

Claude project enablement lives in `.claude/settings.local.json` (symlinked to
`.agents/settings.local.json`) and must include `agentic-relay` in
`enabledMcpjsonServers`.

### Codex CLI

Workspace config lives in `.codex/config.toml`:

```toml
[mcp_servers.agentic-relay]
command = "npx"
args = ["-y", "@rk0429/agentic-relay@latest", "mcp", "serve"]
```

### Gemini CLI

Workspace config lives in `.gemini/settings.json`:

```json
{
  "mcpServers": {
    "agentic-relay": {
      "command": "npx",
      "args": ["-y", "@rk0429/agentic-relay@latest", "mcp", "serve"]
    }
  }
}
```

### Verify

```bash
claude mcp list
codex mcp list
gemini mcp list
```