# Grok Fleet > Deploy headless third-party CLI worker fleets (Grok, Codex, Antigravity/agy) for volume research or critique work while Claude orchestrates, judges, and files. Use when the user wants to "deploy Grok agents", run a fleet, fan out cheap parallel web-research or critique workers, or offload bulk retrieval and second-opinion work from Claude. Not for correctness-critical single answers (Claude does those directly) or private-data drafts (a local model's slot). - Skill: `campbellsmurphy/grok-fleet` (Agent Skill) - Install (CLI): `npx skillmds@latest add campbellsmurphy/grok-fleet` - Raw SKILL.md: https://api.skillmd.com/api/skills/campbellsmurphy/grok-fleet/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: campbellsmurphy (https://skillmd.com/u/campbellsmurphy) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/campbellsmurphy/grok-fleet --- # Worker fleets Run headless third-party CLI workers in parallel for volume work. Claude writes the specs, controls concurrency, judges output, and files results. The point is cost asymmetry: these workers sit on subscription quotas that are separate from the orchestrator's, so bulk retrieval and breadth-first sweeps can run wide while the expensive model does only the thinking. Everything below is measured, not guessed. The numbers are the whole value of this skill; they were paid for in failed runs. ## The ladder Orchestrator (Claude) writes specs, judges, files. Workers do volume. A local model takes anything that must not leave the machine. Keep the orchestrator for hard, agentic and correctness-critical steps. Three worker fleets, on three separate quotas, which is why it is worth having all three wired: | Fleet | Command | Quota | Notes | |---|---|---|---| | Grok | `grok -p` | Grok Build balance, **finite**, resets weekly | Strongest at driving open APIs and form-driven indexes | | Codex | `codex exec` | ChatGPT subscription | Independent of the Grok balance, so never run a Grok-only wave | | Antigravity | `agy -p` | Google quota | Third pool; the binary is `agy`, not `gemini` | **Standing rule: never fan out one fleet without launching another alongside it.** A single-fleet wave leaves free capacity idle, and one fleet's exhaustion stalls the work. ## Worker invocation, the load-bearing flags Grok: ``` grok -p "" --output-format json --effort high --max-turns 44 --disallowed-tools use_tool ``` - `--max-turns` at least 12, and **44 for research agents**. The CLI turns big inline prompts into file reads that consume turns, so a low cap yields silent empty output. At 20 turns, 2 of 8 research agents ran out mid-hunt and returned only progress narration. - Put this in the prompt too: "breadth-first, fetch only the most promising pages, reserve your final turns to write the full findings report." - `--disallowed-tools use_tool` on volume workers blocks the MCP passthrough. If the worker and your own browser automation share one browser profile, only one side can drive it. - `--output-format json`, then parse `.text` defensively. A JSON schema flag exists and is unreliable (prose leak, null structured output); ask for a labelled JSON block inside the prose and parse it out. Codex: ``` codex exec --skip-git-repo-check -s read-only -c tools.web_search=true -o out/.txt "" < /dev/null ``` - `--skip-git-repo-check` and `< /dev/null` are both mandatory for backgrounded workers. Without them the worker refuses to start, or stalls reading stdin. Antigravity: ``` export PATH="$HOME/.local/bin:$PATH" # the installer only edits interactive shell profiles agy -p "" --print-timeout 300s ``` - **Headless permission wall.** In `-p` mode `agy` cannot prompt, so any tool needing shell permission is auto-denied and the worker returns ZERO bytes with "no output produced". Web search and fetch are fine; shell and script tools are not. Write specs that are explicitly web-only: "use only web search and page fetches; do not run shell commands or write scripts." - It is an agentic CLI with terminal and file tools. Prefer its sandbox flag for research workers, and never skip permissions on anything that could write outside a scratch directory. Wrap every worker in `timeout 900`. A hung worker produces zero output for an hour and retry-once does not catch a hang. ## Fleet ops - **Concurrency: at most 3 heavy agents globally**, not per runner. Two 3-wide runners in parallel is 6 concurrent and is too many; run one wave runner at a time. Tiny calls are clean up to 16, with a sweet spot of 4 to 8. The real limit is the subscription's usage pool, not request rate. - **Retry gate: `.text` longer than 1500 characters.** Not 200: a truncated agent emits a few hundred characters of narration that sails through a low gate. - **Runner pattern.** Write per-agent spec files plus a shell runner (`&` with `wait` every 3, retry loop on the length gate), launch it in the background, write outputs to per-agent files. - **Redeploy supervisor.** Retry-once is not enough when the server is cancelling. Run a background supervisor that, after the wave runner exits, re-globs the spec files, redeploys any spec whose output is under the length gate (at most 2 concurrent), and repeats until success or a deadline. Dropping new specs into the same directory enrols them automatically. - **Waves, not one big blast.** Wave 1 takes broad angles, the orchestrator judges and dedupes against what is already known, wave 2 targets the productive seams carrying wave 1's confirmed anchors. Anchors-forward beats cold breadth every time. - **Spec design.** A shared preamble (only sourced findings, a URL per claim, an explicit NEGATIVE for dry angles, never fabricate) plus a per-agent angle with all known anchors inline. - **Probe before launching**, especially on a metered fleet: one two-turn "reply OK" call. Fire the highest-value specs first. ## Recognising quota exhaustion On a finite balance, the end has a three-stage signature. Learn it, because stage one looks like noise: 1. Workers return `stopReason: "Cancelled"` with only a first-line preamble, a few hundred characters. This is the **early warning**, not transient noise, when it clusters. 2. A worker returns a raw error: `API error (status 402 Payment Required): ... usage balance exhausted`. 3. A fresh probe returns `403 Forbidden: ...spending-limit`. On any of these: kill the runners immediately (`pkill -f "grok -p"`), because retries only burn the orchestrator's tokens. Archive the unrun specs for a later rerun and move the wave to a fleet on a different quota. One nuance: `Cancelled` results with a CLEAN balance probe are transient server-side pressure, not exhaustion, so do not burn more than two retries on the same heavy spec. The relay pattern salvages a dead wave: feed the dead worker's partial discoveries (endpoints, hosts, cookie names) into a finish-the-job spec, or let the orchestrator close it out with curl. ## Task routing, as priors rather than permanent rules Re-test these as the models improve. **Worker-first, where they are excellent:** - **Open, JSON and form-driven indexes.** They discover and drive undocumented APIs unprompted, including CSRF handling, multipart POSTs and parsing values out of embedded JSON arrays. - **Document transcription at volume.** Opening dozens of scanned PDFs or IIIF pages and transcribing them into comparison tables is the single biggest time multiplier over the orchestrator. - **Exhaustive negative sweeps** with a what-was-searched table. Reusable and trustworthy. - **Access workarounds.** Text-extraction proxies, POST versus GET, cookie and parameter discovery. **Orchestrator-first, where workers waste turns or get it wrong:** - **JavaScript single-page apps** and **bot-wall-protected sites**. Asymmetry worth knowing: the orchestrator's own fetch tool sometimes succeeds where a worker is walled, so try it before declaring a source dark. - **Identity adjudication**, and anything weighing evidence you already hold. - **Handwriting-critical fields**, dates especially. A worker misread 27 as 24 on a register. Re-read load-bearing values from the image yourself. ## Blind specs: never put the expected answer in a verification spec A verification re-read echoed THREE values straight out of its own spec (a date, an address, a name) on a record that read differently at full resolution. Give the record locator only. If context is unavoidable, say "a prior read exists; do not assume it is right" with NO field values. A verification read that knows the expected answer is not verification. ## Judging is the orchestrator's job, non-negotiable Worker output is draft-grade until verified: real catches, with occasional confidently-wrong specifics. The signature failure, seen repeatedly, is **treating one mismatched field as disqualifying** instead of weighing the ordinary explanations for why a field disagrees (a name changed, a record was indexed badly, an occupation drifted). Verdicts belong to the orchestrator, never the worker. Before filing or acting on anything: - Spot-check every load-bearing claim against its cited URL, by re-fetching yourself or by sending a second worker as an adversarial verifier. - Cross-fleet verification catches errors in both directions. When the stakes justify it, run a second fleet on the same angles and reconcile; each fleet catches the other's misses. - **Citation hygiene.** Workers sometimes cite a bare site root, or a paywalled source they could not actually read. Demand a specific page URL per claim. Google-grounded answers return redirect wrapper URLs, so capture the real article id on a verification pass. - Access failures are usually tooling, not absence. License workers to try proxy prefixes, POST versus GET and alternate mirrors before accepting a negative on a blocked site. ## Respect site terms Some sites forbid programmatic queries in their terms, and a scripted sweep can cost a paid membership or an IP block. Keep a named do-not-automate list in your own copy of this skill and put it in every spec preamble. Keep search volume modest on sites that degrade under load.