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:

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 "<spec>" --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/<name>.txt "<spec>" < /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 "<spec>" --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.