Skip to main content
Glama

agent-fleet

PyPI Python versions License CI codecov Ruff uv

Assembles a minimal Claude Agent SDK agent from a problem statement and a capability corpus, then runs and resumes it. The generation path is deterministic — no LLM and no network in it, so the same request and corpus produce a byte-identical agent. Running the agent is the part that talks to the SDK.

The runtime remains Claude Agent SDK-specific: Claude is the supervisor and conversation owner. Live and generated Claude agents also receive one guarded in-process MCP tool, mcp__codex__codex_run, for delegating bounded implementation, debugging, and independent-review work to the local Codex CLI. Codex is a worker capability, not a second fleet runtime or an authoritative workflow store.

Repository layout

Python only. One PyPI package (claude-sdk-agent-fleet), three subpackages layered so each depends on the ones below it. pip install claude-sdk-agent-fleet gets the core engine and MCP pool server; claude-sdk-agent-fleet[api] (or [all]) adds the FastAPI service.

Path

What it is

Run or import

Install

src/agent_fleet/

core engine: pipeline, router, pool

imported

claude-sdk-agent-fleet

src/agent_fleet_api/

FastAPI service over the core

run

claude-sdk-agent-fleet[api]

src/agent_fleet_mcp/

MCP server exposing the pool as tools (pool-mcp)

run

claude-sdk-agent-fleet

agent_fleet_api ─┐
                 ├─imports──▶ agent_fleet ──imports──▶ capdisc
agent_fleet_mcp ─┘

The API front-end carries the web dependencies as an optional extra so the core engine carries none by default. Environment scanning lives in capdisc, a separate, public repo consumed as a pinned git dependency.

Related MCP server: agentforge

Pipeline

ProblemRequest ─▶ recall ─▶ select ─▶ compose ─▶ score ─▶ render
                  (source)  (budget)  (AgentSpec) (efficiency) (SDK program)
  • recall — a CatalogSource ranks the corpus by lexical relevance (a pluggable Ranker) and trims to a limit.

  • select — keep candidates above a relevance threshold (plus pinned), capped by tool/skill budgets.

  • compose — map the selected refs into an AgentSpec with a templated system prompt.

  • score — check the spec against tool/skill/prompt budgets (efficiency).

  • render — emit a runnable Claude Agent SDK program.

Pool

AgentPool (SQLite) keys each pooled agent by a stable AgentKey and stores the AgentSpec and session id that built it, so a run can be retrieved, resumed against the same live SDK conversation, or found fuzzily. run_with_capture observes the live message stream to record the real, resumable session id of every agent a run involves — the top-level agent and each dispatched subagent. Runs, per-agent runs, and findings are persisted alongside the entry.

Teammates

The pool's primary MCP surface: a hardcoded roster of templated teammates (src/agent_fleet/engine/teammates.py), addressed by name. spawn_teammate stands one up from its template (toolkits can pin its capabilities) and runs it in the background; check_teammate reads the derived status and persisted outcome; message_teammate revives the standing session. The pool key is teammate.{name}, so the same name always resumes the same conversation.

Consumption is push-style, not poll-in-conversation: set a harness Monitor on check_teammate rather than re-checking it from inside the conversation. AGENT_FLEET_NOTIFY_COMMAND configures a Stop-hook shell command that runs when a teammate's run finishes, receiving Claude Code's hook-input JSON on stdin — the payload identifies the finished session.

Guarded Codex worker

Install and authenticate the Codex CLI once:

codex --version
codex login

Every Claude fleet run—including named subagents and emitted agent programs—gets codex_run by default. The tool accepts a self-contained prompt, an absolute canonical Git worktree root, a read-only or workspace-write sandbox, a supported Codex model, reasoning effort, timeout, and an optional prior thread UUID. It returns the final message, thread UUID, commands observed in Codex JSONL, token usage, duration, and bounded failure detail.

Fresh prompts travel over stdin. Codex's documented non-interactive resume form requires a positional prompt, so resumed prompts are capped at 64,000 UTF-8 bytes for macOS process-argument portability; avoid putting secrets in a resume prompt because local process listings can expose command arguments.

The secure defaults are intentional:

  • cwd must stay under an absolute, existing operator-allowlisted directory. An empty root list uses the fleet process working directory, except when that directory is the filesystem root or user home; set an explicit narrower allowlist in those cases.

  • read-only is the default and Codex receives --ask-for-approval never.

  • workspace-write is disabled until explicitly enabled, and then accepts only a clean, detached linked Git worktree.

  • the wrapper never uses --skip-git-repo-check, never invokes a shell, ignores user Codex config for the automated run, explicitly treats the worktree as untrusted so project .codex/ config, hooks, rules, and MCP servers do not load, and pins adjacent controls: no command network, web search, extra writable or temporary roots, hooks, apps, remote plugins, nested agents, login shells, or broad command-environment inheritance.

  • runtime/output are bounded, the whole child process group is terminated on macOS and Linux, and common API/service credentials are removed from the Codex process environment.

  • the pool MCP does not expose a direct Codex endpoint; the running Claude agent is the caller.

Configure the boundary with environment variables:

AGENT_FLEET_CODEX_ENABLED=true
AGENT_FLEET_CODEX_ALLOWED_ROOTS='["/absolute/path/to/repos","/absolute/path/to/worktrees"]'
AGENT_FLEET_CODEX_ALLOW_WORKSPACE_WRITE=false
AGENT_FLEET_CODEX_MAX_TIMEOUT_SECONDS=3600

For implementation workers, set AGENT_FLEET_CODEX_ALLOW_WORKSPACE_WRITE=true, create a detached linked worktree under an allowed root, and pass that exact worktree root to codex_run. Disabling AGENT_FLEET_CODEX_ENABLED removes the server and tool grant entirely.

Develop

uv sync --extra api
uv run pytest
uv run ruff check
uv run mypy src
make coverage       # test coverage, printed to the terminal

Details: docs/OVERVIEW.md · docs/pipeline.md · docs/catalog-boundary.md · docs/live-smoke.md

Coverage

codecov sunburst

Available Tools

10 tools
create_agentA

Assemble an agent for a task and store it in the pool under agent_key, returning the stored entry — the create/update entry point an orchestrating agent uses to stand up a new pooled agent (or re-assemble an existing one).

Inputs: task (required), agent_key (required), name, tags, +5 more. Returns: A pooled agent held in the pool: its spec plus the Claude Agent SDK session UUI…

delete_agentA

Remove the pooled entry stored under agent_key.

This is also the legitimate dismissal path for a teammate: deleting its teammate.* entry discards its standing conversation, and the next run_teammate call re-creates it fresh from its roster template. No guard against the teammate namespace here — unlike create_agent/run_agent, dismissal is intentional deletion, not accidental bypass. Dismissing a teammate with a live run discards that run's record along with the entry, and the still-running background task dies unrecorded when it eventually finishes or fails.

Inputs: agent_key (required). Returns: result

find_agentsA

Rediscover pooled agents by re-describing the problem, ranked most-relevant first — the fuzzy path for when the exact agent_key isn't at hand.

Inputs: query (required), limit. Returns: result

get_agentA

Return the pooled entry stored under agent_key, or None when the pool holds no such entry.

A safe probe: returns None rather than raising when the id is absent, so an orchestrating agent can check existence without handling an error.

Inputs: agent_key (required). Returns: result

get_runA

Return one run record by its run_id, or None when the pool holds no such run.

A safe probe, mirroring get_agent: returns None rather than raising when the id is absent, so an orchestrating agent can check existence without handling an error.

Inputs: run_id (required). Returns: result

list_agent_runsA

List every agent that ran within one run and the real, resumable session id each was given.

This is how an orchestrating agent discovers the independently-resumable session_id of every agent — the run's main/supervisor agent and any subagents it dispatched — that participated in a specific run_id (obtained from list_runs, get_run, or a RunOutcome). Each captured session id can then be used to resume that one agent's conversation on its own, independently of the others, later.

Inputs: run_id (required). Returns: result

list_agentsB

Return every pooled agent, most-recently-updated first.

Returns: Every stored pool entry, newest-updated first.

Inputs: no named parameters. Returns: result

list_findingsA

Return the pooled agent's findings oldest-first — the assembled-document reading order.

Inputs: agent_key (required), run_id. Returns: result

list_runsA

Return every run recorded for agent_key, most-recently-started first.

Inputs: agent_key (required). Returns: result

run_agentA

Run the pooled agent live and record every agent that participates. The entry's first-ever run starts a fresh session; later runs resume it. Requires the claude CLI at runtime.

Every run is granted the full capability set — for the main agent and, when named, for each dispatched subagent: fan-out subagents (resolved from their own pool entries and wired in via with_subagents), the run-scoped findings-writer (with_findings_tool), and dynamic capability acquisition (with_acquire_tool). The findings tool needs the run id at wiring time, so the run is started here and its id handed to run_with_capture rather than minted inside it.

Inputs: task (required), agent_key (required), resume_agent_id, subagent_agent_keys. Returns: The result of a captured run: the main agent's collected text, the finished `Ru…

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct operation: agent CRUD, run listing, run execution, and findings retrieval. No two tools have overlapping purposes, and descriptions clearly differentiate them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, e.g., create_agent, list_agents, get_run. Verbs are imperative and clear, with no mixed conventions.

    Tool Count5/5

    10 tools cover the agent fleet management domain without being excessive or insufficient. Each tool serves a clear purpose in the lifecycle of agents and runs.

    Completeness4/5

    The tool surface covers core agent and run operations (create, read, delete, search, run, list runs), but lacks explicit run modification or cancellation capabilities, which is a minor gap.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Wraps the Claude Agent SDK as MCP servers, letting you spawn multiple specialized Claude Code agents — each with its own model, tools, system prompt, and personality — from any MCP client.
      5
      23
      ISC
    • A
      license
      A
      quality
      D
      maintenance
      MCP server that exposes 300+ AI agents as tools via a single API key. Supports listing agents, invoking any agent with chat-completion style messages, checking agent health, and retrieving platform statistics.
      5
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that enables agents to dynamically switch between multiple AI models (OpenAI, Anthropic, Google, etc.) with unified protocol-driven configuration and capability discovery.
      Apache 2.0