Skip to main content
Glama

Agent Shuttle

Tests MIT license A2A Protocol 1.0 MCP Python 3.11+

Russian version / Русская версия

Agent Shuttle is a Python library and MCP server for working with local Antigravity, Codex, Claude Code, OpenCode, and configured ACP agents. Delegate research, code reviews, implementation and second opinions using the harnesses' existing local authentication.

Use the Python API in your application, or connect the MCP server to your AI assistant. Both interfaces manage local agent tasks, multi-turn sessions, live model catalogs, account quotas and tool-policy guarantees. A2A 1.0 JSON-RPC is the peer protocol. Available research tools, including web access, depend on the selected harness and policy.

File editing tasks can use isolated Git worktrees with explicit change application.


Supported Agent Harnesses

Harness

Primary Integration Mechanism

Auth & Model Access

Key Features

Codex

Official openai-codex Python SDK

Local Codex App Server sign-in

Sandboxes (workspace_write, read_only, full_access), model & reasoning effort catalog, quota reporting via account/rateLimits/read.

Antigravity

Official agy CLI in headless mode (-p / stream-json)

Signed-in Antigravity account

Real-time models, efforts, and /usage quotas. Default settings or full access (--dangerously-skip-permissions). Optional legacy SDK backend.

OpenCode

Managed local HTTP server (--pure serve)

Local Ollama or cloud providers

Configured via JSON profile, fine-grained tool policies (no_tools, read_only, workspace_write, full_access), model variants.

Claude Code

Managed CLI in print mode (claude -p)

Local Ollama endpoint or Anthropic

Configured via JSON profile, isolated temporary session configs, resume support, safe mode vs full access.

Configured ACP agent

Agent Client Protocol over local stdio

Agent's own account and model configuration

Register a command in a JSON profile; streamed updates, cancellation, and capability-gated session loading. Tool policies are advisory.


Related MCP server: pokeclaw

Installation

Agent Shuttle runs on Windows, Linux, and macOS. For the command-line tools and MCP server, install uv first; uv can obtain a compatible Python automatically.

Install the commands and MCP server

uv tool install agent-shuttle
uv tool dir --bin

The last command shows where uv placed agent-shuttle-mcp (with .exe on Windows); use its absolute path in your MCP client's configuration. To use agent-shuttle directly in a shell, run uv tool update-shell if the command is not on PATH, then open a new shell.

To check local harness availability, run agent-shuttle discover; it does not authenticate or send a model request. agent-shuttle doctor <agent> --smoke checks a real model turn when needed. MCP already provides ask_agent for supported harnesses and configured profiles.

Use the Python library in another project

uv add agent-shuttle

uv tool install isolates the tool from your project's Python environment. Install Agent Shuttle as a project dependency when your code imports agent_shuttle.

Install from Local Checkout

You can install Agent Shuttle directly from its repository checkout into your project's virtual environment:

# Create and activate your virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# Install in standard or editable mode
pip install C:\path\to\agent-shuttle
# or editable mode during development:
# pip install -e C:\path\to\agent-shuttle

Once installed, the CLI tools (agent-shuttle, agent-shuttle-mcp) and Python API (agent_shuttle) are fully accessible inside that virtual environment. The original checkout directory does not need to stay in place for runtime imports. Version 0.8 uses Shuttle names throughout the Python API, environment, HTTP routes, and A2A metadata. See connection and release guidance before restarting existing servers.

The distribution has one Python package: src/agent_shuttle/. This is the standard src layout; there is no second implementation or compatibility package.


Quickstart

Install the MCP server, then give your MCP client its absolute executable path:

uv tool install agent-shuttle
uv tool dir --bin

Point your MCP client's command at agent-shuttle-mcp in the printed directory. MCP starts a local A2A peer when a request needs one; there is no separate server startup step. See the getting started guide for MCP configuration and harness setup.

For a persistent server, run agent-shuttle serve codex --workspace . --port 8765 (or serve antigravity on port 8766) in a terminal and stop it with Ctrl+C.


Minimal Examples

1. Python API

import asyncio
from pathlib import Path
from agent_shuttle import ShuttleClient, HarnessLaunch, connect_harness

async def main():
    client = ShuttleClient()

    # Query live model catalog and quota information
    info = await client.info("http://127.0.0.1:8766")
    print("Selected model:", info["capabilities"]["selected_model"])

    # One-shot task
    result = await client.ask(
        "http://127.0.0.1:8766",
        "Explain the project structure and list entry points.",
        model="gemini-3.8-flash-medium",
        reasoning_effort="medium",
    )
    print(f"[{result.state}] Task {result.task_id}:\n{result.text}")

    # Persistent multi-turn session (preserves conversation context)
    async with client.session(
        "http://127.0.0.1:8765",
        model="gpt-5.6-terra",
        reasoning_effort="high",
    ) as session:
        step1 = await session.ask("What database migrations are pending?")
        step2 = await session.ask("Generate SQL to apply the first migration.")
        print("Step 2 response:", step2.text)
        print("Step 2 token usage:", step2.usage)

    # Managed peer lifecycle: reuse existing server or start a temporary one
    launch = HarnessLaunch(
        name="antigravity",
        url="http://127.0.0.1:8766",
        workspace=Path.cwd(),
    )
    async with connect_harness(launch) as conn:
        print("Connected to:", conn.url, "(spawned temporary:", conn.started, ")")

asyncio.run(main())

2. Command-Line Interface (CLI)

# Discover locally installed harnesses without starting models
agent-shuttle discover

# Check installation and connection without a model turn
agent-shuttle doctor
agent-shuttle doctor --profile .\examples\opencode-ollama.json

# After fixing a reported issue, verify one real turn (uses model tokens)
agent-shuttle doctor codex --smoke

# Start an A2A server for Codex
agent-shuttle serve codex --workspace . --port 8765

# Start an A2A server for Antigravity (CLI mode)
agent-shuttle serve antigravity --workspace . --port 8766

# Start an A2A server from a profile (OpenCode, Claude Code or ACP)
agent-shuttle serve profile --profile .\examples\opencode-ollama.json --workspace . --port 8767

# Query server capabilities, models, and quota limits
agent-shuttle info http://127.0.0.1:8765

# Send a task from the command line
agent-shuttle ask http://127.0.0.1:8765 "Summarize recent changes" --model gpt-5.6-terra

doctor reports installation, connection and turn verification separately. Its default run checks built-ins and local profiles registered in AGENT_SHUTTLE_AGENTS_JSON; missing optional runtimes are skipped. OpenCode and Claude Code need a JSON profile for connection checks. --json provides the same report for scripts. Exit codes are 0 for passed checks, 1 for a failed target or smoke turn, and 2 for invalid invocation or configuration. --smoke requires one target and uses enforced no_tools (or Codex read_only); ACP smoke is rejected because ACP cannot enforce those restrictions.

Register an ACP agent

Copy examples/acp-worker.json, set command to the installed agent's ACP launch command, and set workspace to the project directory. command is an argument array; it is never run through a shell. provider, default_model, allowed_models, and reasoning_efforts are optional for ACP. Without allowlists, an explicit model or effort may select any variant advertised in the session's ACP config options; configured allowlists narrow those choices.

agent-shuttle discover --profile .\examples\acp-worker.json
agent-shuttle serve profile --profile .\examples\acp-worker.json --port 8768
agent-shuttle info http://127.0.0.1:8768
agent-shuttle ask http://127.0.0.1:8768 "Explain this project" --tool-policy read_only

For MCP managed startup, map an arbitrary ID to the profile in AGENT_SHUTTLE_AGENTS_JSON:

{"my-acp": {"harness": "acp", "profile": "C:/profiles/my-acp.json"}}

ACP discovery checks the command without starting the agent. info performs the ACP handshake and reports negotiated capabilities without sending a model prompt. ACP policies are advisory: results include a warning, and read_only_tools remains false because the agent may use tools outside client permission requests. Use a verified external sandbox when an enforceable restriction is required.

3. Model Context Protocol (MCP)

Start the stdio MCP server:

agent-shuttle-mcp
# or: python -m agent_shuttle.mcp_server

Available MCP tools:

  • ask_agent(agent_id, prompt, model?, reasoning_effort?, tool_policy?, workspace?): Reuses a matching local A2A server or starts a temporary one. Built-in IDs are codex, antigravity, opencode, and claude_code; configured ACP IDs require a JSON profile in AGENT_SHUTTLE_AGENTS_JSON.

  • get_agent_info(agent_id, workspace?): Fetches live models and quotas, starting a temporary server if needed.

  • ask_antigravity(prompt, model?, reasoning_effort?, workspace?, tool_policy?, turn_timeout_seconds=300): Starts an Antigravity server if one is not running.

  • ask_codex(prompt, model?, reasoning_effort?, workspace?): Starts a Codex server if one is not running.

  • get_antigravity_info(workspace?) & get_codex_info(): Read live capabilities and quota without burning model turns.

  • submit_task(agent_id, prompt, model?, reasoning_effort?, tool_policy?, workspace?, request_id?): Start a long task and return its ID immediately.

  • check_task(task_id), wait_task(task_id, timeout_seconds?), cancel_task(task_id): Inspect, wait for, or stop a task.

  • get_result(task_id, cursor?, limit?), get_transcript(task_id, cursor?, limit?): Read bounded pages of output and history.

  • get_events(task_id, cursor?, limit?), get_event_page(task_id, seq, cursor?, limit?): Read Shuttle's ordered event journal and full data for a truncated event. Save total_size to poll after the current end.


Key Concepts

Harness Discovery

Run agent-shuttle discover (or discover_harnesses() in Python) to inspect local executables without launching processes or loading weights. It checks PATH and platform-specific standard installation directories (%LOCALAPPDATA%\agy\bin, npm global directories, etc.). Custom paths can be specified via environment variables (AGENT_SHUTTLE_AGY_COMMAND) or CLI flags (--agy-command, --opencode-command, --claude-command).

Model & Reasoning Selection

Model parameters are passed as A2A metadata keys (agent_shuttle.model, agent_shuttle.reasoning_effort):

  • Antigravity: Reasoning effort is embedded in model IDs (e.g. gemini-3.8-flash-medium). If both --model and --effort are passed, they must match.

  • Codex: Model and reasoning effort are configured independently according to the catalog returned by get_codex_info.

  • OpenCode & Claude Code: Profiles define allowed_models and optional reasoning_efforts (such as model variants for Ollama or CLI flags).

Workspaces & Session Isolation

  • Every server binds to a strictly validated, canonical workspace directory.

  • connect_harness() verifies that an existing server's workspace matches the caller's target workspace before reusing it.

  • Sessions: ShuttleSession maintains a stateful conversation across multiple ask() calls. Conversation settings (model, effort, tool policy) are pinned at session creation and cannot be changed mid-session. Idle sessions are cleaned up automatically after 30 minutes.

  • Library task lifecycle: TaskManager runs agents directly from Python, with no A2A or MCP server. It owns task IDs, sessions, a SQLite event journal, cancellation, result paging, preferences, and interruption recovery. A2A projects the same task ID and result through its protocol; MCP continues to reach those tasks through managed A2A peers. See the Python API.

  • Remote task lifecycle: ShuttleClient.submit() returns a remote TaskHandle immediately. Use status(), bounded wait(timeout), live events(), Shuttle-only events_page() and event_page(), result_page(), transcript(), result(), or cancel(); reopen a task by ID with client.task(url, task_id). A wait timeout does not stop the agent. An optional UUID request_id deduplicates retried submissions. Standalone servers can persist tasks with --task-db; MCP task tools do this automatically in the workspace's .agent-shuttle directory. Completed results survive restart; interrupted work is marked failed without replay. See the API reference.

Safety & Tool Policies

Agent Shuttle defines four standardized tool policies:

  • no_tools: Disables tool invocations entirely.

  • read_only: Permits non-mutating search and file reading.

  • workspace_write: Allows editing files within the designated workspace.

  • full_access: Explicitly unclamps all tool restrictions and approval prompts.

For configured ACP agents, these policies are advisory. Agent Shuttle checks ACP permission requests but cannot prevent an agent from acting outside them. See the permissions guide.

WARNING

full_access grants the worker unrestricted tool access for that task. --agy-dangerously-skip-permissions enables that capability for the Antigravity server. Keep servers on loopback. Antigravity's explicit scoped read_only policy is enforced by its verified PreToolUse hook; an implicit/default CLI policy does not provide the same guarantee.


Testing

Agent Shuttle provides a comprehensive offline test suite using fake backends that execute without network access, credentials, or model quota consumption:

GitHub Actions runs this same suite on Windows, Ubuntu Linux, and Apple Silicon macOS (macos-15), each with Python 3.11 and 3.12. The process smoke uses only a local Python worker and checks process-tree cleanup; no agent CLI or account is needed.

python -m unittest discover -s tests -v

Live integration tests against real models are separate, opt-in checks and are not part of the six CI jobs. They can be executed by specifying target environments (e.g. AGENT_SHUTTLE_LIVE_OLLAMA_MODEL=qwen3.5:9b or AGENT_SHUTTLE_LIVE_AGY_FULL_ACCESS=1). See CONTRIBUTING.md for full instructions.


Documentation Index

See installed harness selection.

Available Tools

19 tools
apply_task_changesB

Explicitly apply reviewed changes if touched source files still match the base.

Inputs: task_id (required), expected_revision (required), allow_partial.

ask_agentA

Delegate research, code review, implementation or a second opinion to a local AI agent: Antigravity (antigravity), Codex (codex), OpenCode (opencode), Claude Code (claude_code), or an agent_id from list_agents. Делегирование: исследование, ревью, реализация, второе мнение. Use for an actual request to have another agent perform work. Answer general explanations and advice directly; mentioning an agent or a second opinion alone does not request delegation. Shuttle manages local servers automatically. Inspect get_agent_info before selecting an enforceable tool policy; research including web access depends on that agent's capabilities. For Antigravity web research choose web_research when advertised; read_only allows local files only. Preserve the user's explicit agent and model. Use submit_task for long work.

Inputs: prompt (required), agent_id (required), model, workspace, +2 more.

ask_antigravityC

Delegate to Antigravity. Default: read_only; choose workspace_write for file edits.

Scoped policies enforce native file tools and block shell/MCP/subagents. Servers and per-conversation permission hooks are managed automatically.

Inputs: prompt (required), model, workspace, tool_policy, +2 more.

ask_codexC

Delegate to Codex, launching its A2A server when absent. Omit model unless requested.

Inputs: prompt (required), model, workspace, tool_policy, +1 more.

cancel_taskB

Stop the delegated task and wait for backend cleanup; repeated cancellation is safe.

Inputs: task_id (required).

check_taskC

Read the current task snapshot without waiting for the worker.

Inputs: task_id (required).

discard_task_changesC

Explicitly delete an isolated task's saved change and owned worktree.

Inputs: task_id (required).

get_agent_infoA

Inspect live models, account quota and enforceable tool policies for Antigravity, Codex, Claude Code, OpenCode or a configured ACP agent before delegating research, review, implementation or a second opinion. Manages the local server automatically. This checks live metadata without a model turn; use list_agents for offline inventory.

Inputs: agent_id (required), workspace.

get_antigravity_infoB

Read Antigravity's current models, effort options and account quota without an agent turn.

Inputs: workspace.

get_codex_infoA

Read Codex's current models, supported efforts and account quota without an agent turn.

Inputs: workspace.

get_event_pageC

Read full JSON data for a journal event with data_truncated=true.

Inputs: seq (required), task_id (required), limit, cursor.

get_eventsB

Read Shuttle's ordered event journal. Save total_size to poll after the current end.

Inputs: task_id (required), limit, cursor.

get_resultC

Read a bounded result page; follow next_cursor until it is null.

Inputs: task_id (required), limit, cursor.

get_task_changesB

Describe an isolated task's saved changes; no files are modified.

Inputs: task_id (required).

get_task_diffC

Read a bounded page of an isolated task's Git binary patch.

Inputs: task_id (required), limit, cursor.

get_transcriptB

Read a page of A2A task history and artifacts; status updates may be absent.

Inputs: task_id (required), limit, cursor.

list_agentsA

Discover local Antigravity, Codex, Claude Code, OpenCode and configured ACP agents for delegation, research, code review, implementation and second opinions. Lists agent_id, command availability and configuration errors without starting agent processes, contacting models or verifying authentication. Use get_agent_info for live readiness, models and tool policies. Поиск агентов для делегирования задач. Use when asked to discover actual available local agents or while preparing authorized delegation. General explanations and advice about agents or second opinions do not require an inventory of the user's installed agents.

Inputs: no named parameters.

submit_taskA

Delegate research, code review, implementation or a second opinion to a local AI agent: Antigravity (antigravity), Codex (codex), OpenCode (opencode), Claude Code (claude_code), or an agent_id from list_agents. Делегирование: исследование, ревью, реализация, второе мнение. Use for an actual request to have another agent perform work. Answer general explanations and advice directly; mentioning an agent or a second opinion alone does not request delegation. Shuttle manages local servers automatically. Inspect get_agent_info before selecting an enforceable tool policy; research including web access depends on that agent's capabilities. For Antigravity web research choose web_research when advertised; read_only allows local files only. Preserve the user's explicit agent and model. Use submit_task for long work. Returns a task ticket immediately; use check_task/wait_task, then get_result. Reuse request_id when retrying submission.

Inputs: prompt (required), agent_id (required), model, workspace, +4 more.

wait_taskC

Wait within a separate budget; expiry returns a snapshot and never cancels work.

Inputs: task_id (required), timeout_seconds.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 19 tools

    Disambiguation2/5

    Four tools perform delegation with near-identical purposes: ask_agent, submit_task (whose description is literally identical plus one sentence), ask_antigravity, and ask_codex. Likewise get_agent_info, get_codex_info, and get_antigravity_info overlap, leaving the agent to guess whether to use the generic or per-backend variant. The read-side tools (get_result, get_transcript, get_events, get_event_page) are distinguishable only by careful reading.

    Naming Consistency4/5

    Almost everything follows a verb_noun snake_case pattern (get_result, submit_task, check_task, wait_task, cancel_task, list_agents, get_task_diff). Minor deviations exist: ask_antigravity/ask_codex drop the '_agent' suffix used by ask_agent, and apply_task_changes/discard_task_changes use a three-part noun phrase.

    Tool Count3/5

    At 19 tools the surface is heavy and includes clear redundancy: ask_antigravity/ask_codex duplicate ask_agent, and get_codex_info/get_antigravity_info duplicate get_agent_info. The task lifecycle (submit/check/wait/cancel/diff/apply/discard) legitimately needs several tools, but a leaner set would be easier to navigate.

    Completeness4/5

    The domain is well covered end-to-end: discovery (list_agents), capability inspection, sync and async delegation, polling, waiting, cancellation, paginated results, transcripts, event journal, and diff review/apply/discard. Gaps are minor, e.g. no explicit follow-up message or task listing/cleanup operation.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Wraps Claude Code as tools for MCP clients, enabling autonomous coding tasks via a 4-tool lifecycle with session management, async polling, and permission controls.
      4
      57 npm
      21
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables MCP clients to spawn and control Codex CLI and Claude Code sessions on the host machine, with session management and filesystem access.
      4
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Agent orchestration system that runs coding-agent sessions (Claude Code, Codex) with policy mediation and exposes tools via MCP.
      -
    • A
      license
      B
      quality
      B
      maintenance
      Enables launching and supervising local Codex and Claude Code agent sessions and one-shot tasks, exposing run, list, stop, and output operations over MCP with session-scoped permissions and sandbox controls.
      2
      264 npm
      1
      MIT