Use Coding Agents — Installed CLIs as Plain Sub-agents

Validated on fedora 2026-09-04 by running each command on a minimal prompt (write one file, or reply OK). pop-os is set up identically via control/install.sh. Run hostname first. Re-run <agent> --help before relying on any flag not listed here.

Principle

Every agent here is a worker: it receives a prompt, edits files in one directory, commits, prints a result, exits. Nothing more.

• Do not use the CLIs' own orchestration features. No droid --mission, no codex multi_agent, no hermes delegate_task / moa / kanban, no grok --agents, no opencode personas. Those are unvalidated here, spend tokens invisibly, and hide state from the orchestrator.
• The orchestrator is the session running this skill (normally claude via the Agent tool or a lifeos skill). It plans units, writes prompts, launches workers, reads short results.
• Workers are interchangeable. Pick by availability and cost, not by feature.

Workers

Facts from --help: grok 1.0.13 has no --check / --best-of-n; droid rejects --auto together with --skip-permissions-unsafe; hermes restores the previous session's cwd unless --in is given.

Getting the result back

Simplest contract, works everywhere: tell the worker to write its output to a file and print one line DONE|BLOCKED|FAILED <reason>. Read the file, not the transcript.

Cheaper / capped variants (validated)

Use when a unit is small. Same worker, fewer tokens:

• claude: --model haiku --max-turns N (do not add --bare or --setting-sources ""; both drop auth)
• codex: -c model_reasoning_effort=low (minimal is rejected)
• droid: -r low -m claude-haiku-4-5-20251001
• grok: --max-turns N --no-subagents --disable-web-search
• vktr: --max-turns N (lean toolset and one request per prompt are already the default)
• opencode: --variant minimal
• pi: --thinking off

Listing and picking models

Validated 2026-09-04. Pass the id with the agent's model flag (--model / -m).

Viktor (vktr): the worker that knows the company

vktr is a Grok Build fork whose only model is viktor, the company's AI employee. It runs as the key owner's own Viktor, so it can see what that person's Viktor sees: Slack, Linear, GitHub, Notion, analytics, its skills. Same worker contract as grok.

• Ask Viktor for context the repo can't give. Who owns X, what a Slack thread decided, a Linear issue, a customer's state, logs or metrics. Ask instead of guessing: vktr -p "<question>" --json → read .text. Without grants it is read-only.
• As a worker: vktr -p "<prompt>" -w <name> --always-approve --deny 'Bash(git push*)'. Long prompts: --prompt-file f. Resume: -r <sessionId> or -c. Headless skips an untrusted repo's AGENTS.md silently; look at it, then pass --trust once.
• Another CLI on Viktor: vktr launch --viktor claude -p "..." (also codex, opencode, pi).
• Install: curl -fsSL https://raw.githubusercontent.com/viktor-com/vktr/main/install.sh | sh (no root; ~/.vktr/bin, linked from ~/.local/bin).
• Key: a personal Viktor API key with scope chat:completions. Only its owner can create it, at app.viktor.com/settings/api-keys. Save it with vktr login, which prompts with hidden input, or set VIKTOR_API_KEY. Never put a key on a command line, in a repo or in a prompt. vktr doctor shows where the key comes from and checks it live.
• No key → the worker prints BLOCKED no Viktor key: run vktr login. Never search for one.
• Every call spends Viktor workspace credits. Use it for context and Viktor-shaped tasks, not as a bulk code editor.

Isolation

Two workers must never write the same file in the same tree. Use a worktree per worker: claude -w <name>, droid -w <name>, grok -w <name>, hermes --worktree; for codex, opencode, copilot, pi run git worktree add first and cd into it. (Worktree flags checked in --help only.)

Resume instead of restart

claude --resume <id>, codex exec resume --last, droid exec -s <id>, grok -r <id>, hermes --resume <s>, opencode run -s <id>, copilot --continue, pi -c. Resume a BLOCKED worker with the missing fact rather than re-dispatching cold.

Fan-out pattern

d=$(mktemp -d /tmp/orch-<slug>-XXXX)
cat > "$d/preamble.md" <<'P'
You are working on <project> at <code_path>.
Read CLAUDE.md / AGENTS.md / README.md first if present.
Commit with clear messages when done. Do not ask questions.
Do not start or reinstall opencode.service; the OpenCode daemon is retired.
Write your result to <unit_file> and print ONLY one line: DONE|BLOCKED|FAILED <reason>.
Before DONE, compare your diff and the observed result with the unit's Acceptance. If only a
proxy passed (tests, a build, a plan) or a gate is still open, print BLOCKED and name what is unmet.
After a tool error, do the next step it names before calling that tool again (table in
~/.agents/skills/use-coding-agents/SKILL.md, "Error → next step"). Never resend the same failing call.
P
cat > "$d/unit-1.md" <<'U'
Task: <what to do>
Acceptance:
- Deliver: <artifact or path>
- Scope: may change <paths>; must not touch <paths>
- Proof: <command or observation in the target environment>, not a proxy
- Gates: <checks and approvals to wait for; stop at a withheld one>
- Report: <format>
U
cd <code_path>
mkdir -p $d/cache-{1..5}   # one writable cache per worker; a shared /tmp cache breaks gh
XDG_CACHE_HOME=$d/cache-1 claude -p "$(cat $d/preamble.md $d/unit-1.md)" --dangerously-skip-permissions > $d/1.log 2>&1 &
XDG_CACHE_HOME=$d/cache-2 codex exec --dangerously-bypass-approvals-and-sandbox < <(cat $d/preamble.md $d/unit-2.md) > $d/2.log 2>&1 &
XDG_CACHE_HOME=$d/cache-3 droid exec --skip-permissions-unsafe -f <(cat $d/preamble.md $d/unit-3.md) > $d/3.log 2>&1 &
XDG_CACHE_HOME=$d/cache-4 grok -p "$(cat $d/preamble.md $d/unit-4.md)" --always-approve -w unit-4 > $d/4.log 2>&1 &
XDG_CACHE_HOME=$d/cache-5 opencode run "$(cat $d/preamble.md $d/unit-5.md)" --auto > $d/5.log 2>&1 &
wait; tail -n1 $d/*.log

Prompts live on disk and are dispatched by path. The orchestrator authors nothing itself (same discipline as timeboxed-iterating).

Acceptance contract

Every unit prompt carries the Acceptance: block above, filled in. A unit without it is not ready to dispatch. Read a DONE against the same block, not against the worker's summary. When the user corrects a result, rewrite the unit's Acceptance: from the correction before resuming or re-dispatching; the worker's first line restates what changed and what will prove it.

Error → next step

Repeat calls after an error that already said why were the main avoidable cost in long runs.

Rules

• Plain workers only. If you reach for a CLI's mission / delegation / persona feature, stop and fan out from the orchestrator instead.
• One unit, one directory, one commit per worker. Merge worktrees afterwards.
• Logs under /tmp or the scratchpad, never in the repo.
• Cap loops with --max-turns where it exists, otherwise a turn budget in the prompt.
• Bypass flags only in a worktree, in grokc, or in a repo you can git reset.
• Backlog.md stays human. Workers do not touch backlog/tasks/.
• Smoke tests are one word. Validate a recipe with "Reply with the single word OK." only.
• Shared machines: your home only. On a multi-user box or fleet, act only inside your own user's home. Never read or change another user's sessions, worktrees, agent configs or keys. Fleet-wide installs are an admin task, not a worker task.
• Do not invent flags. Not in this file → run --help and paste the real one.

Related skills

• overnight — dispatch approved work items to these workers in the background
• timeboxed-iterating, workgraph, workmachine, gauntlet, dark-factory, bughunt — orchestration loops that use these workers