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

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:

{
  "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:

pnpm benchmark:nf

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

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:

{
  "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:

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

Gemini CLI

Workspace config lives in .gemini/settings.json:

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

Verify

claude mcp list
codex mcp list
gemini mcp list