---
name: ai-cli-selection
description: "Decision tree for selecting the right AI CLI worker — teaches Hermes when to handle tasks directly vs delegate to Aider, OpenCode, Codex CLI, or Open Interpreter"
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    tags: [selection, routing, coding-agents, workflow]
    related_skills: [aider, autonomous-coding-agents, open-interpreter]
---

# AI CLI Selection Guide

## Critical Rule: Do the Work, Don't Delegate the Command

**Never hand the user a command to run themselves.** If a task calls for a coding agent, Hermes invokes it directly via `terminal(background=true)` or PTY mode. The user will correct you if you pass work back — they expect the agent to execute, not instruct.

## Desktop vs CLI Tool Placement

| Machine | Tool Form | Examples |
|---------|-----------|---------|
| **Debian** (server, GPU) | **CLI** — headless, colocated with inference | `opencode run`, `aider`, `interpreter`, `codex exec` |
| **CachyOS** (desktop, KDE) | **Desktop GUI** — Electron apps | `opencode-desktop`, `Interpreter AppImage`, `codex app` |

**⚠️ Critical: Desktop apps do NOT read the same config files as CLIs.**
- OpenCode Desktop uses its own Electron-leveldb store at `~/.config/ai.opencode.desktop/` — it ignores `~/.config/opencode/opencode.json`
- To make OpenCode Desktop see providers, run `opencode serve` on Debian and connect the Desktop to it
- Interpreter Desktop has its own settings panel — configure manually through its GUI
- After installing a CLI tool on the server, sync the configs to CachyOS via scp automatically

## Decision Tree

When Hermes receives a task, route using this priority:

### Tier 0: Handle Directly (No Delegation)

**Do these yourself with Hermes tools — no external agent needed:**

- Shell inspection (ls, find, grep, process list, disk usage)
- File searches (search_files, read_file)
- Small edits to known files (patch, write_file)
- Log analysis (terminal + grep)
- Simple scripts (<20 lines, Python/bash directly)
- CSV/JSON inspection
- git status / git log / basic git operations
- Low-value tasks (file renames, permission fixes, simple config changes)

### Tier 1: Aider → Surgical Edits

**Delegate to Aider when:**
- Change is in 1-3 well-known files
- Task is precisely defined ("change X to Y in file Z")
- SQL corrections or database migration edits
- Small refactors with known target files
- Test-driven implementations of simple functions

```bash
aider-local 'Add validation to the email field in user.py'
```

**After Aider finishes — ALWAYS:**
1. `git diff --stat` — see what changed
2. `git diff` — inspect each change
3. `pytest -x -q --tb=short` — re-run tests
4. `ruff check` — re-lint
5. NEVER trust Aider's self-report of completion

### Tier 2: OpenCode → Exploration & Broad Work

**Delegate to OpenCode when:**
- Unfamiliar repository (needs discovery pass)
- Coding against local models through llama-swap
- OpenRouter model usage (opencode has native support)
- Broad code reviews across the whole codebase
- Multi-file changes where the scope isn't fully known

```bash
opencode run -m local-gateway/qwen36-35b-mtp 'Add input validation and error handling to the API layer'
opencode run -m local-gateway/qwopus-9b 'Review all recently changed files for security issues'
```

### Tier 3: Codex CLI → Complex Autonomous Tasks

⚠️ **Codex CLI 0.139.0 `--oss` only supports Ollama/LM Studio.** Does NOT support custom OpenAI-compatible endpoints (llama-swap etc.). For local-model complex tasks, use **OpenCode** instead. Codex CLI works best via its cloud API.

**Delegate to Codex CLI when:**
- Bounded multi-file implementation (4-10 files, well-defined scope) — **only with cloud auth**
- Root-cause debugging of test failures
- Test-driven fixes with clear pass/fail criteria
- Complex refactoring across module boundaries

```bash
codex exec 'Implement the user authentication module with JWT tokens and refresh flow'
codex exec 'Fix all failing tests in the tests/ directory'
```

**After Codex CLI finishes — ALWAYS:**
1. `git diff --stat` — see scope
2. Inspect critical paths
3. Re-run the specific test suite
4. NEVER trust Codex CLI's self-report

### Tier 4: Open Interpreter → Data & Automation

**Delegate to Open Interpreter ONLY for:**
- Data transformation pipelines (CSV/JSON/XML)
- Large document batch processing (100+ files)
- Reusable execution profiles
- Multimedia automation (image/audio/video processing)
- Tasks where its code execution loop is advantageous

```bash
interpreter --profile local-data 'Process all CSV files in /data: normalize dates, fill NaN values, output clean files'
```

## Cloud Models (OpenRouter + DeepSeek)

### OpenRouter — Paid Models (via Hermes `openrouter` provider)

| Model | Context | Output | Best For |
|-------|---------|--------|----------|
| `qwen/qwen3-coder` | 131K | 16K | Coding (default OR) |
| `qwen/qwen3.7-max` | 131K | 32K | Max quality / complex |
| `qwen/qwen3.7-plus` | 131K | 32K | High quality coding |
| `minimax/minimax-m3` | 1M | 64K | Huge context tasks |
| `minimax/minimax-m2.7` | 1M | 64K | Huge context, cheaper |
| `xiaomi/mimo-v2.5` | 131K | 16K | Fast affordable |
| `xiaomi/mimo-v2.5-pro` | 131K | 32K | Better quality, reasoning |
| `google/gemma-4-31b-it` | 262K | 16K | Open-weight, free tier |
| `nvidia/nemotron-3-ultra-550b-a55b` | 131K | 16K | 550B MoE, best reasoning |

**Usage:**
- Hermes: `/model openrouter/qwen/qwen3-coder`
- Aider: `aider --model openrouter/qwen/qwen3-coder`
- OpenCode: `opencode run -m openrouter/qwen/qwen3-coder '...'`

### OpenRouter — Free Models (26 available)

| Model | Notes |
|-------|-------|
| `qwen/qwen3-coder:free` | Free tier of Qwen Coder |
| `google/gemma-4-31b-it:free` | Free tier of Gemma 4 31B |
| `google/gemma-4-26b-a4b-it:free` | Gemma 4 26B MoE free |
| `nvidia/nemotron-3-ultra-550b-a55b:free` | 550B MoE free tier |
| `nvidia/nemotron-3-nano-30b-a3b:free` | Nano MoE free |
| `meta-llama/llama-3.3-70b-instruct:free` | Llama 3.3 70B free |
| `openai/gpt-oss-120b:free` | OpenAI's open model |
| `openrouter/free` | Auto-routes to best free |
| ... and 18 more | See full list in deliverables |

### DeepSeek

| Model | Context | Output | Best For |
|-------|---------|--------|----------|
| `deepseek-v4-flash` | 1M | 16K | Default, fast, huge ctx |
| `deepseek-v4-pro` | 64K | 8K | Reasoning-heavy, slower |

**⚠️ DeepSeek models consume the first N tokens for internal reasoning** before producing visible output. Always set `max_tokens` >= 256 (ideally 1024) — short prompts with low token budgets return empty `content`. See `references/deepseek-reasoning-tokens.md` for details and per-tool settings.

**Usage:**
- Hermes: `/model deepseek/deepseek-v4-pro`
- OpenCode: `opencode run -m deepseek/deepseek-v4-flash '...'`
- Interpreter: `interpreter --profile ds-flash`

## Model Selection by Task

| Task | Recommended Model | Cold Load | t/s (constrained) | l t/s (actual) | Notes |
|------|------------------|-----------|-------------------|----------------|-------|
| Complex coding | `qwen36-35b-mtp` | ~44s | 0.6 | ~48 (with MTP) | Best reasoning, 21 GB MoE |
| Fast edits | `qwopus-9b` | ~20s | — | ~46 (with MTP) | Coder-tuned 9B Q6_K |
| Data processing | `gemma-12b` | ~8s | 4.6 | — | 256K ctx, clean output, QAT |
| Quick helpers | `qwen35-9b-mtp` | ~7s | 2.3 | ~46 (with MTP) | Fastest cold load |
| Summaries/naming | `gemma-12b` | ~8s | 4.6 | — | Best quality-per-t/s ratio |
| Heavy analysis | `gemma-26b` | ~42s | 1.1 | ~53 (with MTP) | 26B MoE QAT, best quality |
| Fast & cheap | `bonsai-8b` | ~6s | 8.5 | — | 1-bit ternary, 1 GB VRAM |

*Cold load = time from first request to first token (llama-server starts on demand). Constrained t/s = test suite measurement with short outputs. Actual t/s = llama-server internal metrics with proper MTP.*

## Invocation Patterns

```bash
# Background (parallel work)
terminal(command="opencode run '...'", workdir="~/project", background=true, notify_on_complete=true)

# PTY for interactive sessions
terminal(command="codex exec '...'", workdir="~/project", pty=true)

# Foreground for quick tasks
terminal(command="aider-local 'Fix the typo in src/main.py'", workdir="~/project")
```

### Cross-Machine Invocation

When the target machine uses **fish shell** (e.g. CachyOS):
- **Never use heredocs or complex quoting in SSH commands** — fish parses `$()`, `"`, and `'` differently.
- **Always scp config files** to the target, then run with `bash -c` wrapper:
  ```bash
  scp config.json user@host:/path/ && ssh user@host 'bash -c "command"'
  ```
- For OpenCode on a remote machine: scp the `opencode.json` config, then invoke via SSH.

## Critical Rule

**Never mark a task as complete based solely on the agent's self-report.**
Always independently inspect the diff and re-run verification yourself.