CLI Agents
CLI agents are one of ADHDev's main workflows. Today ADHDev ships 8 built-in CLI providers in the catalog. They run through the daemon's PTY/session-host layer after the provider is enabled and detected on the target machine, so you can watch terminal output, type from the dashboard, and keep sessions moving from desktop or mobile.
Agents like GitHub Copilot and Goose aren't built-in CLI providers — they connect over the Agent Client Protocol (stdio) instead. See the ACP agents guide for those.
WARNING
Built-in does not mean verified support. Unless a provider is explicitly promoted in the compatibility docs, treat it as unverified. Verification status is currently under full re-verification — see Supported Providers.
Built-in CLI Providers
| Agent | Command | Verification | Description |
|---|---|---|---|
| Antigravity CLI | adhdev launch antigravity-cli | Unverified | Google's Antigravity terminal agent |
| Claude Code | adhdev launch claude | Unverified | Anthropic's Claude coding agent |
| Codex CLI | adhdev launch codex-cli | Unverified | OpenAI's Codex terminal agent |
| Cursor CLI | adhdev launch cursor-cli | Unverified | Cursor's terminal agent workflow |
| Grok CLI | adhdev launch grok-cli | Unverified | xAI's Grok terminal agent |
| Hermes | adhdev launch hermes-cli | Unverified | Hermes coding agent |
| Kimi | adhdev launch kimi | Unverified | Moonshot's Kimi coding agent |
| OpenCode CLI | adhdev launch opencode | Unverified | Open-source terminal coding agent |
Want to drive a CLI agent that isn't in this table? See Custom Providers for how to add one yourself with a provider manifest.
Why CLI Matters
CLI agents are often the fastest way to keep work moving because they:
- stay close to your repo and shell workflow
- work well over remote terminal control
- avoid IDE-specific UI breakage
- let ADHDev stream the exact terminal session, not a reconstructed abstraction
If you want the most reliable remote workflow today, CLI agents are usually the first path to validate. Verification status for individual providers is currently being redone — check Supported Providers for the current state before relying on a specific promotion.
Launching a CLI Agent
# Strong default paths
adhdev daemon
adhdev launch claude
adhdev launch codex-cli
adhdev launch cursor-cli
# Additional built-in CLI providers
adhdev launch antigravity-cli
adhdev launch grok-cli
adhdev launch hermes-cli
adhdev launch kimi
adhdev launch opencodeBefore launch, make sure the provider is enabled in the machine's Providers tab and that Detect succeeds for the configured executable. If the binary is installed outside the default PATH, set a custom executable path/args there first.
The daemon spawns the CLI process with a PTY, streams output to the dashboard, and forwards your input back to the process.
Ordinary launches are treated as fresh sessions. If you want continuity, use an explicit resume path such as History or hosted runtime recovery instead of relying on implicit auto-resume.
WARNING
Each CLI tool handles its own authentication. ADHDev manages the PTY session and remote control layer, not the upstream tool's login flow.
Folder-trust pre-grant
kimi, grok-cli, codex-cli, claude-cli, and antigravity-cli register a folder-trust scheme with ADHDev, so a fresh launch in a new directory skips that tool's one-time "Do you trust this folder?" prompt instead of stalling on it. Trust is pre-granted using the same trust store the tool would write to itself the first time you approved it interactively.
Terminal Workflow
CLI providers in ADHDev now use the terminal view as the primary workflow. That means the terminal is the source of truth for:
- output and progress
- approval prompts
- tool execution flow
- reconnect and scrollback behavior
Terminal View
CLI agents appear in the dashboard with a full interactive terminal powered by xterm.js:
- Full TUI rendering — colors, cursor movement, progress bars, and approval prompts
- Remote input — type directly from the dashboard
- Scrollback restore — PTY buffer is replayed after reconnect
- Mobile-friendly control — practical for quick approvals and lightweight supervision
Session Recovery
CLI runtimes are no longer treated as disposable one-shot launches. ADHDev keeps a hosted runtime layer so sessions can often be recovered after disconnects or daemon restarts.
That recovery path is operator-driven: users should explicitly choose Resume / History / hosted runtime recovery actions when they want continuity. A normal fresh launch should not silently reopen an older session.
If a CLI session disappears from the main dashboard, check:
- Hidden tabs
- Activity inbox
- History
- the machine's Hosted Runtimes tab
For command-line recovery, start with the primary user-facing runtime surface:
adhdev runtime list
adhdev runtime attach <runtimeTarget>
adhdev runtime recover <runtimeTarget>
adhdev runtime restart <runtimeTarget>
adhdev runtime snapshot <runtimeTarget><runtimeTarget> accepts the session ID, runtime key, display name, or a unique prefix shown in adhdev runtime list.
If you prefer shorter commands for the common path, adhdev attach <runtimeTarget> and adhdev recover|resume <runtimeTarget> are direct shortcuts for the same runtime surface.
If you need low-level diagnostics or explicit operator controls, use:
adhdev daemon:session-host
adhdev daemon:session-host --session <sessionId> --resume
adhdev daemon:session-host --session <sessionId> --restart
adhdev daemon:session-host --prune-duplicatesThis is the right path when the runtime still exists but the active dashboard session is stuck or attached to the wrong copy.
History and resume depth still varies by provider. A built-in CLI can launch cleanly and still remain Unverified for resume flows until that path is explicitly tested.
Agent Settings
Each CLI agent supports configurable settings via the dashboard gear button:
| Setting | Description |
|---|---|
| Notifications | Show state-change notifications |
| Auto Approve | Auto-approve tool execution where supported |
| Approval Alerts | Notify when approval is needed |
| No Progress Alert | Warn when a turn shows no progress for too long (formerly labeled "Long Generation Alert") |
| No Progress Threshold | Threshold in seconds before the no-progress alert fires |
Auto-Approve Modes (1.0.60+)
Beyond the single on/off "Auto Approve" toggle above, every built-in CLI provider now declares its own set of launch-time auto-approve modes — a picker shown when starting a session, not the gear-button setting. Each mode carries a risk tier so you know what you're turning on before you launch:
| Risk | Meaning |
|---|---|
| Safe | Interactive PTY parsing — ADHDev answers prompts it recognizes; nothing is bypassed at the tool level |
| Caution | The provider's own "accept edits" / "auto" flag is passed at launch — broader auto-acceptance, still provider-scoped |
| Dangerous | The provider's full permission-bypass flag (e.g. Claude Code's --permission-mode bypassPermissions, kimi's --auto) — the agent runs commands with no prompt at all. ADHDev shows a confirmation dialog before launching in this mode. |
Available modes differ per provider (they come from that provider's own CLI flags), and the default is always the safe, interactive mode.
Model Discovery (1.0.60+)
The model picker's list is discovered differently depending on the provider:
| How | Providers |
|---|---|
| Runs the CLI's own model-listing command at runtime | codex-cli, grok-cli, cursor-cli, antigravity-cli, opencode |
| Reads the provider's local config file | kimi |
| Not discoverable — the manifest list is used as-is | claude-cli, hermes-cli |
claude-cli's model options (opus/sonnet/haiku/fable) are stable aliases rather than versioned slugs, so they don't drift the way a discovered list would; hermes-cli picks its model interactively inside its own TUI with no listing command to call.
Quota Reporting
adhdev quota <provider> prints a provider's current usage reading. adhdev quota refresh [providers...] asks the running daemon to actually refetch and update its cached reading (what routing and the dashboard read from), respecting any active rate-limit cooldown.
Quota reporting is available for: claude-cli, codex-cli, kimi, opencode, grok-cli, cursor-cli, antigravity-cli (7 of the 8 built-in CLIs). hermes-cli has no quota reporting — it exposes no model-axis usage data to read.
CLI vs ACP
| Feature | CLI Agent (PTY) | ACP Agent (stdio) |
|---|---|---|
| Interface | Full terminal session | Structured chat protocol |
| Rendering | xterm.js / raw terminal | Markdown / content blocks |
| Best fit | Real shell workflows, TUI tools, remote supervision | Protocol-native agents with structured events |
| Verification model | Unverified by default; validate per provider | Unverified by default; validate per provider |
Troubleshooting
Agent doesn't launch
- Verify the tool is installed locally
- Enable the provider in the machine's Providers tab and run Detect
- Set a custom executable path/args if the binary is outside the default PATH
- Check upstream auth or API keys
- Inspect local health with
adhdev daemon:status
Terminal is blank
- The tool may be waiting for input
- Check connection status in the dashboard
- Check Hidden tabs, inbox, and history before starting a duplicate session
- If the runtime survived, recover it through Hosted Runtimes instead of relaunching immediately
Terminal output looks wrong
- Restart the session if the upstream tool left the terminal in a bad state
- Treat the terminal view as the canonical output for CLI providers
- If the problem persists, treat it as a provider compatibility issue and check the compatibility pages first
Session shows an approval prompt with nothing to approve (1.0.60+)
Some CLIs can block on a step outside the terminal itself — the clearest example is grok-cli's browser-based sign-in. ADHDev now tracks this internally as a distinct state so such a session lands in your approval inbox instead of silently reading as idle or generating (it shows there as a normal waiting-for-you item, not a separate badge). Complete the external step (e.g. finish the browser sign-in) and the session resumes normally.