RelayKit

Harness augmentation for multi-tool, human-in-the-loop parallel execution.

RelayKit augments existing harnesses like Codex, Claude Code, Gemini CLI, and Antigravity so one operator can run parallel lanes, assign deliberate roles, and keep the human in charge of coordination instead of treating every tool as a generic assistant.

Task intake, lane recommendation, onboarding, checkpoints, handoffs, and learning are the main mechanisms. They exist to make existing harnesses behave like one operator-directed system.

RelayKit now also keeps lightweight issue state for critique-driven work, so old review docs do not have to act like permanent backlog forever.

If you do not trust the recommendation engine for a given task, RelayKit can still run as an orchestration layer: provide the phase, setup, and lane assignments yourself, then use confirmations, checkpoints, advances, resume flows, and reflections on top of that operator-defined plan.

Quick Start

Install RelayKit:

pipx install "git+https://github.com/pavelalbawork/RelayKit.git"
pipx ensurepath

That is the normal install path. It does not require cloning the repo first.

If you are developing locally or want an editable install from a checkout, clone the repo and install from the working tree instead:

git clone git@github.com:pavelalbawork/RelayKit.git
cd RelayKit
pipx install -e .
pipx ensurepath

Wire your host:

relaykit setup --host codex

If your shell still says command not found: relaykit, reload it once:

exec zsh

If you want to continue immediately without reloading the shell, use the direct pipx app path once:

~/.local/bin/relaykit setup --host codex

Swap codex for claude-code, gemini-cli, or antigravity.

Supported hosts:

• codex
• claude-code
• gemini-cli
• antigravity

Run setup once per host you actually want RelayKit available in. To wire all supported hosts in one pass:

relaykit setup --all-hosts

Then restart your host and say:

Use RelayKit MCP tools directly.

When the host starts using RelayKit, the operator rhythm should stay explicit:

• confirm the task before real work starts
• checkpoint after the first concrete artifact, blocker, or verified finding
• advance immediately on blocked, needs_reroute, or ready_for_next_phase
• summarize RelayKit state for the user instead of pasting raw MCP payloads

If you want your host to reach for RelayKit earlier on multi-tool work, add this instruction to your host or workspace guidance:

When the user wants to parallelize work across Codex, Claude Code, Gemini CLI, or Antigravity,
or says "parallelize", "split the work", "use all my tools", or "distribute this",
use RelayKit for intake and lane assignment before execution starts.

That is the main first-use path. Most users should stop there.

If That Fails

If pipx is unavailable or your Python setup blocks it, use the built-in fallback:

python3 scripts/relaykit.py install-self
python3 scripts/relaykit.py setup --host codex --force

Then restart your host and use the same prompt:

Use RelayKit MCP tools directly.

Remove RelayKit Completely

If you want a clean uninstall, do it in this order:

1. remove RelayKit-managed host wiring
2. uninstall the package
3. delete copied skill folders only if you used the skills-only fallback

Remove host wiring:

relaykit uninstall-host --host codex
relaykit uninstall-host --host claude-code
relaykit uninstall-host --host gemini-cli
relaykit uninstall-host --host antigravity

Uninstall the package:

pipx uninstall relaykit

If you installed RelayKit into a manual virtualenv instead of pipx, remove that venv or run pip uninstall relaykit inside it.

If you copied skills manually, remove those folders too:

rm -rf ~/.claude/skills/relaykit*
rm -rf ~/.gemini/skills/relaykit*
rm -rf ~/.codex/skills/relaykit*

If you want your agent to help with cleanup, say:

Remove RelayKit from this machine completely, including host wiring and any copied skill folders.

What setup Does

relaykit setup is the normal onboarding command. It:

• wires the selected host
• runs a safe local smoke test
• prints concise next steps for entering the MCP path

In a normal terminal, setup now prints a short human-readable summary by default. Use --format json if you want the full machine payload.

The RelayKit MCP server also returns human-readable text content for the main task lifecycle tools while keeping the full machine payload in structured content. Agents should show the summary, not paste raw JSON back to the user.

The setup smoke is pinned to the host you selected, so relaykit setup --host codex verifies a Codex-only path instead of drifting to another host during the smoke recommendation.

Run it once per host you want to use with RelayKit. For example:

relaykit setup --host codex
relaykit setup --host claude-code

Or wire all supported hosts in one pass:

relaykit setup --all-hosts

Use relaykit host-status --host <host> when you want a readiness check without changing anything.

Orchestration-Only Mode

Recommendation is optional. If you already know the right phase and lane split, start RelayKit from an explicit plan and skip inference:

relaykit start-task \
  --workspace-root . \
  --task "Ship the backend fix and review it" \
  --task-scope workspace \
  --intake-mode manual \
  --plan-json '{
    "phase_mode": "implementation-phase",
    "setup": { "coordination": "coordinated", "continuity": "lean" },
    "task_parts": [
      { "part_id": "backend", "role": "builder", "host": "codex", "objective": "Own the backend fix." },
      { "part_id": "verify", "role": "reviewer", "host": "claude-code", "objective": "Verify and gate the fix." }
    ]
  }'

Or use the human-first shell flow with the same explicit plan:

relaykit run \
  --workspace-root . \
  --task "Ship the backend fix and review it" \
  --task-scope workspace \
  --intake-mode manual \
  --plan-json '{
    "phase_mode": "implementation-phase",
    "setup": { "coordination": "coordinated", "continuity": "lean" },
    "task_parts": [
      { "part_id": "backend", "role": "builder", "host": "codex", "objective": "Own the backend fix." },
      { "part_id": "verify", "role": "reviewer", "host": "claude-code", "objective": "Verify and gate the fix." }
    ]
  }'

Use intake_mode=guided when the host or operator is supplying a structured plan that still came from an interactive question flow. In both guided and manual, RelayKit preserves the provided plan and focuses on orchestration instead of recommendation.

More Install Options

Install directly from GitHub (recommended for normal use):

pipx install "git+https://github.com/pavelalbawork/RelayKit.git"
pipx ensurepath
relaykit --version
relaykit-mcp --help

This is the simplest path for most users. No local checkout is required.

Clone the repo locally first (recommended for development):

git clone git@github.com:pavelalbawork/RelayKit.git
cd RelayKit
pipx install -e .
pipx ensurepath

If you want a local working copy without keeping the upstream remote attached:

git remote remove origin

Editable pipx from a local checkout:

pipx install -e .
pipx ensurepath
relaykit --version
relaykit-mcp --help

Run that from inside the RelayKit repo checkout. If you are not in the repo directory, replace . with the full checkout path.

If relaykit is still not found right after install, your current shell has not reloaded the updated PATH yet. Run exec zsh, open a new terminal, or use ~/.local/bin/relaykit once.

pipx installs into an isolated environment and puts relaykit and relaykit-mcp on your PATH globally. No venv activation, works from any directory or shell.

The installed relaykit-mcp entry point is the preferred MCP launch path across Codex, Claude Code, Gemini CLI, and Antigravity. It avoids raw source-tree config and keeps host wiring consistent.

Manual venv — explicit fallback:

python3 -m venv .venv
source .venv/bin/activate
pip install -e .
relaykit --version
relaykit-mcp --help

With the venv flow, use the full venv path in any MCP config: .venv/bin/relaykit-mcp.

Skills only — zero dependencies (optional fallback):

cp -r skills/ ~/.claude/skills/

Copies the skill surface directly. No Python required. Use this only if you want portable RelayKit skills without the CLI or MCP server.

MCP Server

If your host supports MCP, add this to its config:

{
  "mcpServers": {
    "relaykit": {
      "command": "relaykit-mcp"
    }
  }
}

relaykit-mcp is registered as an entry point during install — no path needed. It is a long-lived stdio server backed by the official Python MCP SDK. relaykit-mcp --help and relaykit-mcp --version are safe to run; no arguments starts the server.

If you installed via venv instead of pipx, use the full path:

{
  "mcpServers": {
    "relaykit": {
      "command": "/path/to/relaykit/.venv/bin/relaykit-mcp"
    }
  }
}

bootstrap-host can write this config automatically for supported hosts, so manual MCP editing should be the exception, not the default.

Quick Start

Use RelayKit when you want multiple harnesses to behave like coordinated lanes in one human-directed system.

Start a task:

relaykit start-task --workspace-root . --task "Build the login page"

Lifecycle commands now default to a concise human-readable view in an interactive terminal. Use --format json when you want the raw machine payload for scripting or debugging.

If you want the guided shell version instead of stepping through individual commands, use:

relaykit run --workspace-root . --task "Build the login page"

RelayKit now makes the preflight verdict explicit in recommendations:

• manual means the task is probably too small for protocol overhead
• lean means a light protocol path is worth it
• full means durable continuity or a research lane is justified

Answer clarification questions until you get a recommendation:

relaykit answer-task --workspace-root . --task-id <id> --answer "Keep it to one component."

Confirm and execute:

relaykit confirm-task --workspace-root . --task-id <id> --accept

If RelayKit decides a task is so small and bounded that the protocol is not worth it, confirm-task will stop and recommend manual coordination instead. Use --force-protocol only when you explicitly want RelayKit state and handoffs anyway.

For small bounded coordinated tasks that still benefit from the protocol, RelayKit now defaults to coordinated+lean. In that path, confirm-task returns a launch_bundle immediately with ultra-compact handoff cards and compact launch markdown, so you usually do not need separate render-task-part calls unless you want a verbose packet or need to re-render later.

Checkpoint, resume, and reflect when done:

relaykit checkpoint-task --workspace-root . --task-id <id> --notes "Header done, form next."
relaykit resume-task --workspace-root . --task-id <id>
relaykit reflect-task --workspace-root . --task-id <id> --split-worth-it yes --tool-fit good

Use resume-task for the operator view. If you need ready-to-send packets for the remaining active parts after an interruption, use:

relaykit resume-handoff --workspace-root . --task-id <id>

For lean coordinated phases, prefer the batched path:

relaykit checkpoint-phase --workspace-root . --task-id <id> --reports '[{"part_id":"implementation","notes":"builder ready"},{"part_id":"critique","notes":"critic agrees"}]'
relaykit render-consolidation-packet --workspace-root . --task-id <id>

The compact consolidation packet keeps the full per-part reports in the structured payload while summarizing them in the markdown handoff by default. Use --verbosity verbose when you want the full inline report text. The lean path is optimized for low-overhead handoffs; use render-task-part --verbosity verbose when a receiving host needs the full prompt stack and richer context.

RelayKit also tracks a phase mode for each task (research-phase, review-phase, or implementation-phase) and carries a per-part output contract in handoff packets. If a research-first lane starts producing implementation output or unsupported research claims, checkpoint-task, checkpoint-phase, and render-consolidation-packet now surface phase warnings instead of letting the drift stay invisible.

RelayKit also watches for repo/state drift. If files are changing while a task is still only recommended, or a phase is active but nobody has checkpointed a concrete result yet, show-task, resume-task, and inspect-task now surface drift warnings and orchestration guidance so the operator knows when to confirm, checkpoint, or advance the task state.

RelayKit now also tracks source artifact status for referenced critique and research Markdown files. Follow-up fix packets can mark source issues as addressed-unverified, and show-task / resume-task will mark saved plans as stale when those source artifacts no longer match the backlog they were routed from.

Workspace Setup

Save persistent defaults so RelayKit knows your available tools and models:

relaykit init-workspace --workspace-root . --start-with-defaults
relaykit doctor --workspace-root .

If a host says RelayKit returned Transport closed, do not immediately conclude that RelayKit is unavailable. That usually means the MCP session dropped mid-call. Retry once with:

relaykit doctor --workspace-root .

And, in an MCP-aware host, prefer this sequence:

1. relaykit_ping
2. relaykit_doctor
3. only then fall back to “RelayKit MCP is unavailable” if both fail

If no workspace profile exists yet and you want a non-interactive first-run path, use the guided flow instead:

relaykit guided-setup --workspace-root . --host codex --preset balanced-default

If git_integration is enabled in the workspace or project profile, RelayKit will not create branches during confirm-task. It will return an explicit follow-up step instead:

relaykit prepare-git --workspace-root . --task-id <id>

Example

See the end-to-end walkthrough for a full task lifecycle: intake → clarification → recommendation → builder lane → checkpoint → reflect.

Documentation

• Docs Home — narrative and reading order
• Core Concepts — tasks, roles, lanes, hosts, checkpoints
• Commands — full CLI reference
• Configuration — registry, profiles, presets
• Skills — portable role skills and how to use them
• Personas — optional style/expertise overlays
• Messaging — canonical positioning language
• Landing Copy — website-ready hero, subhead, and blurb
• GitHub Metadata — suggested repo description, topics, and blurbs

Requirements

• Python 3.11+
• Small runtime dependencies: anyio and mcp
• Skills-only install still has no Python dependency requirement

License

MIT