| name | coding-agent-routing |
| description | Use when choosing Hermes vs Claude Code / Codex / Grok Build for coding work, wiring multi-CLI specialist setup, or diagnosing specialist auth/availability on Dewey. |
| version | 1.3.2 |
| author | Hermes Agent (Dewey) |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["Coding-Agent","Routing","Claude","Codex","Grok","Orchestration","Auth"],"related_skills":["claude-code","codex","grok","hermes-agent"],"created_by":"agent"}} |
Coding Agent Routing (Hermes = conductor)
Use this skill whenever a coding/refactor/PR/issue task could be done by Hermes tools or an external coding CLI, or when setting up/auth'ing those CLIs. Hermes is the only conductor. Claude Code, Codex CLI, and Grok Build are specialists (sibling processes).
Architecture (two layers)
| Layer | What it is | Config / auth |
|---|
| A. Hermes brain | Model that runs Hermes (tools, memory, gateway) | hermes model / ~/.hermes/auth.json |
| B. Specialist CLI | External coding agent Hermes spawns via terminal | Separate login per CLI; see references/headless-cli-auth.md |
Do not confuse them. Hermes openai-codex or xai-oauth does not log into codex or grok binaries.
Rule 0 — Hermes alone by default
Do the work with Hermes file/terminal tools when:
- Ops, research, memory, messaging, MCPs, cron, multi-platform
- Small/surgical: ≤3 files, clear patch, roughly under 10 minutes
- Needs Hermes-only context (user memory, gateway UX, standing goals)
- Verification of someone else's work (
git diff, tests)
Do not spawn a specialist for rename-one-function or "what does this file do?"
When to spawn a specialist
Spawn when the job is multi-file / multi-turn agentic coding for ~5–40+ minutes and would bloat Hermes context.
| Job shape | Specialist | Headless invoke (preferred) |
|---|
| Careful large refactor, PR polish, high precision | Claude Code | claude -p '…' --max-turns N |
Git feature builds, codex review, parallel issues | Codex CLI | codex exec '…' (git repo; pty=true) |
| SuperGrok coding quota, scratch without git, parallel Grok worker | Grok Build | grok --no-auto-update -p '…' |
If Claude/Codex are not authenticated or return usage-limit errors, fall back to Grok Build or Hermes alone. Never claim a specialist ran if auth/smoke failed.
Codex usage limits: Auth can succeed while inference fails with a ChatGPT/Codex usage-limit error. Treat as "specialist unavailable"; fall back; do not retry-loop until the stated reset time or credits land.
Standing policy (this machine / Dewey)
Auth snapshot (verify with claude auth status, codex login status, test -f ~/.grok/auth.json if unsure):
- Claude Code: Claude Max (
nickv@testkey.com) — preferred careful multi-file specialist
- Codex CLI: ChatGPT logged in — may hit usage limits; fall back if inference errors
- Grok Build: SuperGrok OAuth (
~/.grok/auth.json) — default fallback / SuperGrok coding / no-git
- Conductor brain: Hermes model stays as configured (often
xai-oauth / Grok). Do not flip brain mid-task without user ask.
- Default coding solo (when a specialist is warranted):
- Prefer Claude Code for careful multi-file work
- Prefer Codex for git-centric builds/reviews/batch issues when not usage-limited
- Prefer Grok Build when xAI quota is the point, no git, or Claude/Codex unavailable
- One writer per dirty tree. Parallel work → separate git worktrees.
- Verify always. After any specialist:
git status/git diff, tests if applicable. Specialist stdout is a self-report.
- Risk: auth/payments/destructive → no yolo; tight allowed tools; Hermes reviews before commit/push.
- Low risk autonomous: Claude skip-permissions (print mode preferred); Codex
--full-auto; Grok --always-approve.
Quick decision checklist
- Hermes-only tools needed? → Hermes
- Scope S (≤3 files)? → Hermes
- Scope M/L agentic coding? → pick specialist by table
- Multiple independent issues? → worktrees + one specialist each
- Unsure? → one builds, Hermes reviews the diff
Auth stores (do not confuse)
| Product | Auth | Powers |
|---|
| Hermes providers | ~/.hermes/auth.json | Hermes brain only |
| Grok Build | ~/.grok/auth.json | grok binary |
| Claude Code | Claude login / CLAUDE_CODE_OAUTH_TOKEN | claude binary |
| Codex CLI | codex login → ~/.codex | codex binary |
Hermes openai-codex or xai-oauth credentials do not log into the specialist CLIs.
Headless setup recipes (device-auth, Claude FIFO paste, smokes): references/headless-cli-auth.md.
Pre-flight before spawn
- Binary on PATH (
command -v claude|codex|grok).
- Auth status / auth file present.
- Optional cheap smoke; on usage-limit or auth error → fall back. Do not spin.
Headless Claude auth (operator checklist)
When completing Claude login on headless hosts, follow references/headless-cli-auth.md (FIFO + script). Hard rules:
- Never inject an OAuth paste whose
#state does not match the live waiter URL.
- Dead PKCE sessions cannot be revived; restart one clean waiter and give the user only that URL.
process submit fails if background stdin is /dev/null — use the FIFO recipe, not bare background.- SIGTERM notices for killed waiters are noise; only the live
state= in /tmp/claude-auth.out counts.
Project context
- Portable:
AGENTS.md (cwd)
- Claude:
CLAUDE.md / .claude/
- Hermes-only:
.hermes.md
- Grok Build also reads CLAUDE.md / AGENTS.md
Related skills
Load before orchestration: claude-code, codex, grok.
Anti-patterns
- Two auto-approve agents on one dirty tree
- Specialist for a one-line fix
- Trusting "done" without reading the tree
- Assuming Hermes OAuth = CLI login
- Stacking brain=X and specialist=X for a 2-minute task
- Injecting a Claude OAuth code from a previous/killed login attempt
- Concurrent
claude auth login waiters (wrong PKCE challenge)
- Retry-looping Codex after a usage-limit error
Hermes control surfaces (not coding specialists)
Prefer Hermes UI over specialist desktops for agent hosts. Full decision table: references/hermes-surfaces-vs-specialist-desktop.md.
| Surface | When |
|---|
| CLI / TUI / gateway | Default Dewey ops |
hermes dashboard --no-open --port 9119 | Visual config + embedded chat on Orgo (loopback; tunnel if remote) |
hermes desktop | Optional Electron if user lives in Orgo GUI |
| Claude Desktop / Codex Desktop | Human preference only; not Hermes integration. Codex Desktop has no official Linux app. |
Dashboard: long-lived background=true daemon; ready log HERMES_DASHBOARD_READY port=9119; probe curl … http://127.0.0.1:9119/. On Orgo, do not claim the user can see it after only browser_navigate or CUA capture. Required path: orgo-desktop doctor (nonblack paint) → orgo-desktop open-url http://127.0.0.1:9119 → orgo-desktop screenshot with nonblack pixels + window title (full recipe: orgo-desktop-local → references/hermes-dashboard-on-orgo.md). Surfaces decision table: references/hermes-surfaces-vs-specialist-desktop.md.
Smoke script
bash ~/.hermes/skills/autonomous-ai-agents/coding-agent-routing/scripts/smoke-specialists.sh
Checks claude / codex (incl. usage-limit) / grok OAuth-only / dashboard :9119 without dumping secrets.
References
references/headless-cli-auth.md — device-auth + Claude FIFO PKCE (canonical auth cookbook)references/hermes-surfaces-vs-specialist-desktop.md — dashboard / Electron / Claude|Codex desktop decisionsscripts/smoke-specialists.sh — board smoke (claude/codex/grok/dashboard)
Success criteria
- Right layer used (Hermes vs specialist)
- Diff/tests verified by Hermes
- Concrete summary of files changed
- If auth/setup was involved: smoke or status proved the specialist is usable, not only logged in
