Summon
Summon any AI, from any CLI. One skill, every model as a sub-agent.
Install: npx skills add Nafjan/summon, then just ask your agent.
Summon is a skill that turns one AI agent into a conductor for all of them. Under the hood
it's a tiny, dependency-free dispatcher, and it runs wherever your agent can execute a shell
command:
- **Coding CLIs:** Claude Code, Codex, Cursor CLI, Gemini CLI, Antigravity.
- **T3 Code:** works today — install Summon into the Claude/Codex/Cursor skill roots
T3 discovers (`python install.py --profile t3`). Not a native T3 plugin; see
[skills/summon/references/t3-code.md](skills/summon/references/t3-code.md).
- **AI IDEs:** Cursor, Antigravity, or VS Code with an agent extension. The skill installs
as a slash command, or the agent just shells out to the dispatcher.
- **Desktop agent apps:** the Claude app and the ChatGPT app (formerly Codex), whose agent
modes can run the dispatcher and read the skill.
- **A plain terminal,** where you drive it yourself.
From any of those you can hand a task to another model, run several at once, or convene a
council to make a decision. It also reaches any OpenAI-compatible API, so OpenRouter,
OpenAI, Anthropic, Google, and local models (Ollama, LM Studio) work as agents too.
```
┌──────────────────────┐
any host CLI ────────► │ summon │ ───► claude (Anthropic)
(claude, codex, │ stdlib dispatcher │ ───► codex (OpenAI)
cursor, gemini, kimi, │ one JSON envelope │ ───► cursor-agent (Cursor)
or your terminal) │ no server, no pip │ ───► gemini (Google)
└──────────────────────┘ ───► kimi (Moonshot AI)
└──► agy (Antigravity)
└──► openai-compat (ModelArk / OpenRouter /
OpenAI / Anthropic / Google / Ollama / …)
```
Most multi-agent tools assume one specific CLI is the orchestrator. Summon inverts that:
**any CLI can be the boss.** Your Codex session can summon Claude for a review. Your Claude
session can summon Codex for an adversarial pass. Your terminal can summon a whole council
to decide something. They run in parallel -- add `--worktree` and each editing agent gets
its own isolated branch -- and every result comes back as one JSON envelope you can branch
on.
And because each backend runs on its own login, the subscriptions you already pay for
finally pull together: Claude Max, ChatGPT, Cursor, Gemini, and Antigravity on the same
task, each billed to its own plan, instead of paying for four and using one at a time.
---
## Who it's for
- **Anyone stacking AI subscriptions.** Paying for Claude Max, ChatGPT, Cursor, or Gemini
and only ever using one at a time? summon puts them on the same task together, each billed
to its own plan, so you get the full value of what you already pay for. Using
[T3 Code](https://t3.codes) as the control plane? Same idea — Summon installs into the
skill roots T3's Claude/Codex sessions already load.
- **Developers who live in Claude Code, Codex, or Cursor** (or any other AI coding tool)
and want the *other* models one command away, without leaving the one they're in.
- **Anyone who wants a real second opinion.** Cross-vendor review, where no model grades
its own homework, is built in rather than bolted on.
- **People making decisions with AI** who want more than one model's take: council mode
gets you diverse positions, anonymized peer ranking, and a synthesized recommendation.
- **Power users running fleets of agents:** fan a task across N models in parallel, with
per-backend throttling and resumable batches.
- **Anyone unifying local + cloud models** behind one interface (subscription CLIs *and*
OpenAI-compatible APIs, including self-hosted).
If you just want a chat UI, this isn't it. Summon is a dispatcher: you or another agent
drive it, and it hands back structured results instead of a stream.
---
## What you can actually do with it
- **Cross-vendor code review:** `summon dispatch --agent adversarial-reviewer` sends your
diff to a *different* vendor than wrote the code.
- **Race several implementations:** three models each build the same spec in isolated git
worktrees; you diff the branches and keep the best.
- **Decide by council:** ask "monorepo or polyrepo?" and four diverse models answer, rank
each other anonymously, and a chairman synthesizes a call with confidence and dissents.
- **Swarm over documents:** a manifest of 40 jobs with per-backend concurrency, resumable
if it crashes. Good for reviewing, summarizing, or labeling at scale.
- **Structured extraction:** `--json-schema` validates an agent's final JSON and, on a
backend that supports resume, spends one corrective retry when it does not match.
- **Use local + frontier models together:** an Ollama model and Claude in the same council.
---
## Install
Pick the path that matches your host. All three install the same `skills/summon/` skill tree;
only the destination differs.
### Agent Plugin (Cursor, VS Code, Copilot, Codex)
For clients that support the open [Agent Plugins](https://agent-plugins.org) standard
(Cursor Marketplace, VS Code agent extensions, GitHub Copilot agent plugins, Codex with
plugin support):
- **From a marketplace:** install the **summon** plugin from your client's plugin UI.
- **From a checkout (local dev):** copy or symlink this repo into your client's local
plugin directory. On Cursor that is `~/.cursor/plugins/local/summon/` with `plugin.json`
at the plugin root (this repo already ships that layout). Reload the window after copying.
The plugin bundles `skills/summon/` as-is — no `install.py` step required for plugin hosts.
### Skills registry (`npx skills add`)
**One command. The skill installs itself into your agent:**
```bash
npx skills add Nafjan/summon
```
Your AI agent now has the `summon` skill and knows how to drive it, so you never learn a
flag. Just ask it: *"summon a cross-vendor review of my last commit,"* or *"convene a
council on monorepo vs polyrepo."* Add `-g` to install globally (every project), or
`-a ` to target a specific one. Works with any skills-compatible agent: Claude Code,
Codex, Cursor, Gemini, Antigravity, and claw-likes like openclaw and hermes. Powered by the
open [`skills`](https://www.skills.sh) registry.
You need **Node** (for `npx`), **Python 3.10+** on your PATH, and at least one AI CLI you're
logged into. After installing, ask your agent to run summon's `doctor` check and it lists what's
ready and what's missing. On Windows, if the install hits a symlink permission error, re-run
with `--copy`.
### Multi-host installer (`python install.py`)
**Install into every AI CLI on your machine at once** (multi-host, ownership-safe):
```bash
git clone https://github.com/Nafjan/summon && cd summon
python summon.py doctor # which backends are ready? what's missing?
python install.py # install the skill into every detected AI CLI
```
`install.py` stages atomically, never touches an agent file you already have, and uninstalls
cleanly (`python install.py --uninstall`). Migrating from the old name? `--with-alias` adds a
thin `/sub-agents` alias.
**T3 Code:** T3 discovers Claude/Codex/Cursor skills — it has no Summon host entry of its
own. Target those roots in one shot:
```bash
python install.py --profile t3
python summon.py --doctor # look for the "t3 code" section
```
Full smoke checklist: [skills/summon/references/t3-code.md](skills/summon/references/t3-code.md).
Or let your AI agent set it up for you (it adapts to your machine)
Paste this into your favorite AI CLI (Claude Code, Codex, Cursor, Gemini, …) in a scratch folder:
```text
Set up "summon" for me (github.com/Nafjan/summon), a cross-vendor AI sub-agent dispatcher.
1. Clone https://github.com/Nafjan/summon and cd into it.
2. Run `python summon.py doctor` and tell me which backends are installed (claude, codex,
cursor-agent, gemini, agy) and which are missing. That check reads versions only -- if I
approve a small live call per backend, run `doctor --probe` to verify sign-in and
account eligibility too.
3. Run `python install.py` to install the summon skill into every AI CLI on this machine
(it auto-detects ~/.claude, ~/.codex, ~/.cursor, ~/.gemini, ~/.copilot and never
overwrites my own agents). Add `--with-alias` only if I ask for the legacy /sub-agents name.
4. Run `python summon.py doctor` again and confirm what's now ready.
5. Read README.md and SKILL.md, then summarize: what I can do now, and ONE example command
using a backend I actually have. If a backend I want is missing, tell me exactly how to
install and log into its CLI.
6. Offer to add the "Delegating to summon" snippet from README.md to my host config
(CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules) so you reach for summon on purpose:
cross-vendor review before merge, --council for decisions, --manifest for fan-out. Only
add it if I say yes.
```
You can also skip the skill install entirely and run the script directly:
`python summon.py dispatch --agent reviewer --prompt "…" --cwd "$PWD"`.
**Staying current:** the installed skill is a copy and never self-updates. Re-install or
update via your Agent Plugin client's UI (for plugin installs), run `npx skills update`
(for `skills add` installs), or re-run `python install.py` after a `git pull` (for
installer installs). Every dispatch envelope carries
`summon.scripts_sha256`, so a stale or divergent copy is detectable from any single
result; the version string alone is not enough.
---
## Your first run
```bash
# from any project directory (use an absolute --cwd)
python summon.py dispatch --agent reviewer \
--prompt "Review the diff on this branch for correctness bugs" --cwd "$PWD"
```
Or, once the skill is installed, just tell your AI CLI:
> "Summon the adversarial reviewer on my last commit and give me the findings."
---
## Command surface
Git-style subcommands. The old flat `--flag` form still works too:
| Command | Does |
|---|---|
| `summon dispatch --agent N --prompt … --cwd D` | run one agent (the default action) |
| `summon list` | list available agents |
| `summon models [--cli B]` | invocable models per backend, with a `source` per entry (live query, local config, or static list) |
| `summon doctor [--json]` | backend / setup health check (run this first) |
| `summon manifest FILE` | run a batch swarm (per-backend concurrency, resumable) |
| `summon council --question "…"` | **decide by consensus** of diverse models |
| `summon agent new\|set NAME --set k=v` | scaffold / retune an agent definition |
| `summon version` · `summon help` | version · usage |
`summon` (no args) prints the command list. Everything below is documented in
[skills/summon/SKILL.md](skills/summon/SKILL.md).
---
## How to use it effectively
1. **Pick the right agent, not just the right model.** Agents bundle a model, a persona,
and a report contract. `reviewer` (Codex) reviews; `planner` (Opus) plans; `pair`
(Sonnet) does everyday work. `summon list` shows them; `summon agent new` makes your own.
2. **Chain with `handoff`.** Every result that satisfies the report contract carries
`report.handoff` (an error, timeout or malformed reply may not, which is what
`report_ok` tells you). Paste it into the next dispatch instead of re-explaining;
that's how multi-step work stays cheap.
3. **Trust the envelope, not the prose.** Branch on `status`: a self-reported `BLOCKED`,
and a recognised approval request in the run's final output, are downgraded to
`blocked`. Approval detection matches known markers rather than reading intent, so also
treat `suspect: true` as unverified rather than assuming every stalled run is caught. Check
`model.served` to confirm which model actually did the work (`served: null` means
summon saw no service evidence: no terminal model report and no output tokens, even
when `targeted` names a model).
4. **Review across vendors.** Send code written by one vendor to a reviewer on another.
`docs/PROTOCOL.md` has the rule and the named patterns (debate, async build, competing
hypotheses, consensus).
5. **Put big inputs in files.** For long prompts, write a packet under `--cwd` and pass a
short "read X and follow it" prompt (avoids arg-length limits and sandboxed reads).
6. **Fan out with `manifest`; decide with `council`.** Independent tasks → a manifest
swarm; a judgment call → a council.
Full playbook: **[docs/PROTOCOL.md](docs/PROTOCOL.md)**.
---
## Teach your agent to reach for it (`CLAUDE.md` / `AGENTS.md`)
summon is invoked *by* your coding agent, so it only gets used well if the agent knows
*when* to reach for it. The skill's description triggers it, but a few lines in your host
config make the agent orchestrate on purpose. Drop this into your `CLAUDE.md`, `AGENTS.md`,
`GEMINI.md`, or `.cursor/rules` (whatever your CLI reads):
```md
## Delegating to summon (cross-vendor sub-agents)
When a task is heavy, parallelizable, or would benefit from another vendor's eyes,
dispatch it with the **summon** skill instead of doing everything yourself:
- **Cross-vendor review before merge (house rule).** Never merge a substantive change
reviewed only by the model that wrote it; it shares that model's blind spots. Route
claude/cursor-written code to codex (`reviewer` / `adversarial-reviewer`); route
codex-written code to a claude reviewer (`quick-reviewer`).
- **High-stakes decisions → `--council`.** Convene a vendor-diverse council and let a
chairman synthesize. Disagreement that survives round 2 is worth taking seriously.
- **Independent work → `--manifest`.** Fan several jobs out with per-backend
concurrency; each writes its own result envelope you can inspect.
- **Escalate the hardest problems** to the top tier (an opus agent, or `fable`). Fable
billing depends on the Claude seat and remaining usage: Max/premium seats may use it
for up to 50% of their regular weekly limit at no extra cost, while Pro/standard seats
use usage credits from the start. summon runs the requested model, warns before
dispatch, and reports billing as unknown without a metered API-key route. Keep councils
and swarms diverse; a council of clones is pointless.
Verify, don't trust: branch on the returned `status`; a `report_ok:false` or
`suspect:true` "success" means re-dispatch. Read `warnings` (model fallback, premium
model cost, or an agy read-only dispatch refused/advisory-only). `model.served` proves what actually ran.
Preview a paid fan-out with `--dry-run`, pass `--json-schema` when you need structured
output, chain via `report.handoff` into the next call, and pass `--out` on any
council you cannot afford to lose (the envelope is checkpointed each phase).
```
Tune it to your workflow. The point is that your agent reaches for summon on purpose
(delegate, review across vendors, decide by council) instead of forgetting it exists.
The agent-led installer above can add a snippet like this for you.
### Orchestration practices that hold up
A few habits that keep multi-agent work fast, cheap, and trustworthy:
- **Verify across vendors, not within.** A model reviewing its own output shares its blind
spots. This is the habit that pays off most, and summon puts the other vendor one command
away.
- **Adversarial-verify findings before you act on them.** Have a second (ideally different)
model try to *refute* a claim; a finding that survives is worth trusting. Don't merge on
one pass.
- **Decide by council, converge by chairman.** For a judgment call, N diverse positions
plus anonymized peer ranking plus a synthesis beats one model iterated. `--council` does
exactly that.
- **Keep the orchestrator's context clean.** Delegate the heavy reading and searching to
sub-agents and keep only their `report.handoff`. That's how long chains stay affordable.
- **Prefer structured output for anything you branch on.** `--json-schema` + `parse_ok`
removes brittle "find the JSON" heuristics from your side entirely.
- **Isolate parallel edits.** `--worktree` gives each concurrent agent its own branch,
reducing ordinary checkout collisions; you still review, diff, and merge the winner.
### Pairs well with your other skills
summon just dispatches. It doesn't try to reimplement the thinking-discipline that
dedicated skills already do well; it composes with whatever your CLI has installed. Some
categories that pair well (use what your ecosystem offers):
- **Adversarial code review:** a skill that forces real perspective shifts pairs well with
cross-vendor dispatch. summon sends the diff to a *different* vendor; the review skill
makes that vendor actually critical.
- **Coding discipline:** Karpathy-style guidelines (surface assumptions, keep it simple,
surgical changes) applied by each sub-agent keep a swarm from over-building.
- **Deep-research harnesses:** fan-out, fetch, and verify for the *findings*, with summon
running the cross-vendor verification pass.
- **Planning / spec-driven workflows:** a plan or spec skill decomposes the work; summon
fans the pieces out (`--manifest`) and reviews them across vendors before merge.
- **Project memory / knowledge graph:** a durable-memory skill writes `.agents/memory.md`,
which summon auto-injects into every sub-agent so they never re-learn your conventions.
Rule of thumb: let specialist skills *think*, and let summon route that thinking across
vendors.
---
## What a dispatch returns
```json
{
"status": "success",
"result": "…the agent's full answer…",
"report": { "status": "DONE", "summary": "Reviewed 4 files; 2 findings",
"handoff": "Fix the race in poller.py:88 first",
"left_behind": "none" },
"environment_handoff": { "declared": true, "left_behind": "none" },
"report_ok": true,
"model": { "requested": "sonnet", "targeted": "claude-sonnet-5",
"served": "claude-sonnet-5", "resolved": "claude-sonnet-5" },
"summon": { "version": "2.0.5", "scripts_sha256": "9f2c…" },
"permission": "safe-edit", "permission_flags": ["--permission-mode", "acceptEdits"],
"usage": { "input_tokens": 12038, "output_tokens": 981 }, "cost_usd": 0.084,
"billing": { "source": "subscription", "note": "Claude login" },
"elapsed_ms": 7285,
"resume": { "cli": "claude", "session_id": "0197…" }
}
```
- `report.handoff` → the context to pass to the next call.
- `environment_handoff` → resources the child created and intentionally left behind. It can
cover temporary paths, processes, servers, VMs, or container resources; the caller, not
summon, decides whether to retain or clean them. `declared: false` means no account was made.
- `report_ok: false` on a "success" → also gets `suspect: true`. Agents that skip their
contract don't get believed.
- `model.served` → the model that actually did the work (evidence-based; `null` = no
service evidence observed). `targeted` = what the session was pointed at.
- `timeout` → the timeout budget, whether partial output survived, and the phase Summon can
prove. ACP names its exact protocol stage; a generic CLI remains `backend-execution` because
Summon cannot honestly infer whether the vendor was starting, reasoning, or running a tool.
- Situational fields appear only when they apply: `exit_history` + `original_exit` (a
corrective resume superseded an earlier attempt; every superseded attempt is kept in
order), `result_from_repair` (the first attempt produced no text, so the repaired text is
the answer), `result_path_conflict` (the envelope found at a shared `--results-dir` path
answers a *different* request and was refused rather than served), and `gate`,
`gate_correction_refused` or `gate_repair_refused` under `--gate-with`. A gate's own
retained-resource declaration is nested at `gate.environment_handoff`.
- `summon.scripts_sha256` + `agent_def.sha256` → provenance: which dispatcher build and
which agent definition produced this envelope.
- `billing.source` → did this draw from a **subscription** or metered **api** credits.
- `resume.session_id` → `--resume` for a cheap follow-up.
> **Costs are estimates.** `cost_usd`/`usage` are the CLI's own list-price figures, not a bill. On a subscription they don't equal money spent, and `billing.source` is a best-effort guess. Know your plan's inclusions and limits, and check your provider's latest billing and model notices directly.
---
## Council mode: decide by consensus
```bash
summon council --question "Adopt a monorepo or keep polyrepos?" \
--members planner,reviewer,researcher,pair --chairman fable --rounds 2 --cwd "$PWD"
```
A vendor-diverse council answers independently. With `--rounds 2` they see all positions
anonymized, refine, and rank them; votes aggregate (Borda) into `consensus_ranking`, and
the chairman returns a decision, a confidence, the agreements, the named dissents, and a
next action. It's the llm-council pattern, run over *real cross-vendor CLIs* instead of one
API's models.
---
## Custom & local models (`openai-compat`)
```markdown
---
run-agent: openai-compat
provider: openrouter # or openai / anthropic / google / groq / ollama / lmstudio
model: anthropic/claude-3.5-sonnet
---
```
Built-in providers, plus your own in `providers.json` (or inline `base_url` + `api_key_env`,
empty key for local servers). Same envelope, same `manifest`/`council`. This is how you add
local models and multi-model API access, and how a council becomes a genuine multi-vendor
board. These backends bill your API credits, not a subscription (see [TERMS.md](TERMS.md)).
---
## The starter roster (20 agents, all editable)
Planning/architecture on Claude (`planner`, `architect`, `deep-debugger`,
`security-auditor`, `fable`), implementation + adversarial review on Codex (`implementer`,
`reviewer`, `adversarial-reviewer`, `debugger`, `test-author`), coding on Cursor (`coder`,
`bug-fixer`), research/docs/frontend on Antigravity (`researcher`, `docs-writer`,
`frontend`), and balanced lanes on Sonnet 5 (`pair`, `editor`, `quick-reviewer`, `pr-prep`).
Each is a plain `.md` file: edit, delete, or add your own with `summon agent new`.
`install.py` never overwrites an agent you already have.
---
## How it compares
| | summon | agent-bridge / CCB / claude-codex-collab | cc-fleet | MCO |
|---|---|---|---|---|
| Vendors | **6** (incl. Antigravity headless + any OpenAI-compatible API) | 2–3 | Claude only | 2–3 |
| Any CLI as host | **yes** | mostly Claude-hosted | no | no |
| Structured envelope + lie-detection | **yes** | partial | no | no |
| Consensus / council mode | **yes** (anonymized ranking + chairman) | no | no | no |
| Cost/usage + billing source | **yes** | partial | no | no |
| Worktree + background + manifest fan-out | **yes, from any host** | no | yes (Claude-hosted) | no |
| Runtime footprint | **a folder of stdlib Python** | daemon / MCP / npm tree | plugin | server |
Caveats: those tools have nicer streaming UIs and bigger communities, and summon is a
dispatcher, not a dashboard. Gemini resume isn't supported, because its CLI can't re-target
a headless session.
---
## System requirements
- **Python 3.10+** (3.11+ recommended). Standard library only, so no `pip install` for the
dispatcher itself — the default **agy** path (a stream-json proxy) is stdlib too. Only the
legacy opt-in agy PTY wrapper needs `pywinpty` and `pyte`
(tested with `pywinpty 3.0.3` and `pyte 0.8.2`).
- **At least one backend:** a vendor CLI installed and logged in (`claude`, `codex`,
`cursor-agent`, `gemini`, `kimi`, or `agy`), and/or an API key for an `openai-compat` provider (or
a local Ollama/LM Studio server). `summon doctor` tells you which are installed;
`doctor --probe` spends a small live call per backend to confirm sign-in and eligibility.
- **`git`** if you use `--worktree`.
- **A host that can run a shell command:** a coding CLI, an AI IDE, a desktop agent app, or
a plain terminal. Anything that can invoke `python` and read the skill can drive it.
- **OS:** Windows runs every backend (it's what I use daily). Linux and macOS run all of
them except agy out of the box. CI covers Ubuntu and Windows.
- **Headless Windows behavior:** Summon launches its dispatcher, utility, detached, and
nested backend processes with hidden startup state plus `CREATE_NO_WINDOW`; routine
dispatches do not open terminal windows. A vendor CLI or custom wrapper that explicitly
creates its own GUI remains outside Summon's process-launch boundary.
- **If a popup persists:** the calling agent should invoke Summon directly, leave
`AGY_PTY_WRAPPER` unset so the bundled `agy_stream_proxy.py` is used, and avoid wrapping
the call in `Start-Process` or `cmd /c start`. If a PowerShell helper must use
`Start-Process`, pass `-WindowStyle Hidden`; a custom wrapper must hide its own children
and be reported in the handoff.
You bring the model access; summon just orchestrates the CLIs and APIs you already use.
---
## Security, permissions, and terms (please read)
- **Permissions.** Each agent's `permission:` (`read-only` / `safe-edit` / `yolo`) maps to
that CLI's own sandbox flags. Bundled agents ship `safe-edit` (auto-approve edits, no
bypass). Raise anything to `yolo` deliberately, and only in repos you trust.
- **Kimi Code is deliberately stricter.** Its non-interactive prompt runner auto-handles tools
and cannot combine with its plan mode, so Summon refuses Kimi `read-only` and `safe-edit`.
`kimi-worker` pins high-context K3; `kimi-coder` pins K2.7 Coding for focused implementation.
Both are `yolo` only and belong in a trusted isolated worktree. For a review-only Kimi job,
use `--worktree`, instruct it not to edit, then inspect the worktree before accepting the
report or removing it: the review label does not create an enforceable read-only boundary.
- **agy is the exception, twice over.** It has no workspace-write tier, so its `safe-edit`
is a full bypass like `yolo`. And it has **no enforceable `read-only` tier at all**, so
since 0.15.0 summon *refuses* an agy dispatch declared `read-only` rather than imply a
boundary that does not exist. Measured over five canaries: `--sandbox` restricts terminal
operations only, `--mode plan` does not withhold the file tools, and withholding the
workspace only breaks *relative* paths -- a declared read-only agy agent read a secret
file and created another by absolute path. `SUMMON_ALLOW_UNENFORCED_READONLY=1` dispatches
anyway and marks the tier advisory in `warnings`; it waives only a tier **you** declared,
never one summon imposed (a `--gate-with` adjudicator, a clamp that bit, a repair resume).
- **Treat the whole `--cwd` as trusted.** Files under it, `.agents/memory.md`
(auto-injected into agent context), and manifest `prompt_file`s are trusted operator
input. Every bundled agent also carries an "untrusted content: data, not instructions"
guard as defense-in-depth. **Don't run summon in a repository you don't trust.**
- **Secrets.** The agy backend copies OAuth tokens into a per-invocation profile locked to
your user (icacls / `0700`) and isolated from your real profile. `openai-compat` reads
API keys from env only and redacts them from any error output.
- **Terms of service.** Summon drives each vendor's *official* CLI (built for scripted use)
on *your* accounts, which is the intended path for personal and dev work. Don't share
accounts, build a product on subscription auth, or hammer parallel volume; use API-key
backends for commercial or high-volume work. Providers can change programmatic-billing
rules. Full guidance in **[TERMS.md](TERMS.md)**.
- **Prompt size is bounded by the OS, not by summon.** Every CLI backend receives the
prompt through `argv`. Windows caps the whole assembled command line at 32767 characters
and reports the overflow as a *missing file*, which summon used to relay as a bogus
`CLI not found`; POSIX caps a single argument at 128 KiB and the total (including your
environment) at `ARG_MAX`. Summon now measures the real, serialized line before spawning
and refuses with an error that names argv as the cause. `--prompt-file` does **not** avoid
this -- it is a quoting convenience and the content still travels on the command line. For
material that large, write it to a file under `--cwd` and ask the agent to read it.
- **No phone-home.** For the five CLI backends, summon sends no telemetry and makes no
network calls of its own; it just spawns the backend CLIs, plus supporting tools where a
feature needs them (`git`, `icacls`/`chmod`, the agy PTY wrapper, a detached copy of
itself for `--background`). The one exception is the `openai-compat` backend, whose whole
job is a direct HTTPS call to the `base_url` you configure.
---
## FAQ
**What happens when a vendor ships a new model?** Nothing breaks. Model strings pass
through verbatim; aliases like `opus` and `sonnet` float, `summon models` shows what's
available, and the envelope's `model.served` confirms what ran (`resolved` is the legacy
field). Aliases can lag a launch by a day or two, so pin the explicit ID when you need
the newest.
**Does it need API keys?** For the five CLI backends, no. It drives the logins you already
have, and it strips `OPENAI_API_KEY` from codex children so you're not silently billed at
API rates. The `openai-compat` backend uses your API key by design.
**Is it safe to let an agent install it for me?** Yes. The agent-led prompt clones the repo,
runs `doctor` (read-only) and `install.py` (which never overwrites your files), and reports
back. Read `install.py` first if you like; it's about 460 lines of stdlib.
**Why not MCP?** MCP adds a server and a session dependency for what is fundamentally a
one-shot subprocess/HTTP dispatch. A script you can read beats a protocol you must trust.
(An MCP facade may come later; the envelope won't change.)
---
## Contributing
Contributions are welcome. New backends, agents, and providers are the easy wins.
A new backend is one entry in a registry
([skills/summon/references/adding-a-backend.md](skills/summon/references/adding-a-backend.md));
a new agent is a `.md` file. See **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup, ground rules (stdlib only,
every change tested, secrets redacted), and the PR checklist. Run
`python skills/summon/scripts/test_discovery.py` and `python tests/test_install.py` before a PR.
## Roadmap
Shaped by two extended field reports (a GTM-materials agent and a complex-coding-project
agent). Every validated request is either shipped, scheduled below, or declined with a
reason. Ordering is roughly by priority, not a commitment.
**Shipped since this roadmap was written:** council quorum + `--chairman-fallback` +
per-stage timeouts; the background job registry read path (`jobs list` / `status` / `wait`
with nonce-verified results); install-drift detection in `doctor` and `install.py`;
`--gate-with` approval gating across every execution path; and the argv preflight that
turned an OS command-line overflow from a bogus `CLI not found` into an accurate error.
**Next (scoped):**
- **Honest fan-out rollups**: a durable attempt journal (already present for councils)
extended to manifests, so `usage`/`cost_usd` totals count every round, retry, and
correction instead of undercounting after a crash.
- **Destructive job registry**: `jobs cancel` / `jobs reap` + heartbeats + orphan
envelopes, gated on real OS process identity (start-time via ctypes / `/proc`) so a
reused PID is never killed by mistake.
**Later:**
- **Error taxonomy + `doctor --live`**: distinct statuses (`transport_unreachable`,
`sandbox_network_denied`, `authentication_failed`, `quota_exhausted`, …) that fail fast
instead of retrying, plus a live doctor that probes reachability/auth and warns when a
sibling install has drifted (using the envelope's `summon.scripts_sha256`).
- **Layered roster resolution**: merge `--agents-dir` / `SUB_AGENTS_DIR` > project
`.agents` > user `~/.agents` > bundled, with a `source` per agent, plus neutral
model-tier agents (e.g. a Sol reviewer, an Opus architect) to layer task personas on.
- **Spend governance**: `--max-cost-usd` / `--max-tokens` accumulated caps with
stop-before-chair behavior. (Pre-dispatch cost *estimates* are declined: summon has no
pricing table and won't guess a bill.)
- **`--verify-no-mutations`**: hash git status/diff before and after a read-only agent and
fail the envelope if it changed anything, backstopping the `yolo` + "do not modify" pattern.
- **Capability-aware rosters**: declare `repo-read` / `vision` / `web` / `enforces-read-only`
capabilities so a council can reject an unsuitable member before spending time. The
original motivation (agy cannot read `--cwd`) is obsolete -- agy is repo-capable at
`safe-edit` -- but a sharper one replaced it: agy cannot *enforce* `read-only`, so a
governed review roster needs to express "this role requires a tier the backend will
actually honour" rather than trusting the label.
- **Session forking**: `--fork-session` / `--resume-if-compatible` so resuming a failed
Fable session can fall back to Opus instead of re-pinning the unavailable model.
- **Multi-root input bundles** and a **`--spec` request file** for work spanning several
repos and for reproducible, Windows-friendly invocations.
- **POSIX PTY wrapper** for the agy backend; **Gemini resume** once its CLI exposes a
stable session id; an optional **MCP facade** (the envelope won't change); **envelope
v2** to retire the legacy `model.resolved` in favor of `targeted`/`served`.
**Known limitation:** the durable-run owner lock has a sub-millisecond stale-break/release
window that pure-stdlib cross-platform file operations cannot fully close. For COUNCIL runs,
generation namespacing bounds the worst case to a single duplicate stage dispatch (wasted
spend, not corrupted output), and it requires a process suspended past its lease resuming
inside that exact window; single-machine use does not hit it.
This does **not** extend to manifests. Two manifest runs sharing one `--results-dir` are not
serialized by anything: measured with two real processes, one parent read and reported the
other's answer. summon now refuses an envelope whose `request_sha256` does not match the job
being run (`result_path_conflict`), but that is a safety net, not a lock -- **give each
concurrent run its own `--results-dir`.** Closing it fully would need OS advisory
locks (with their own NFS / suspended-process gaps).
## Credits
Sharpened against the ecosystem: agent-bridge, CCB, claude-codex-collab, cc-fleet, MCO,
swarms, Omnigent, and Karpathy's llm-council. I've run summon privately for months,
dispatching real work across many CLIs every day, and sharpened it hard over the last few
weeks. The results have been good enough that it was worth generalizing and hardening into
this public repo.
## License
[MIT](LICENSE). Do what you like, no warranty. See [TERMS.md](TERMS.md) for the
provider-terms caveats, which are on *you*, not on this software.