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.

WARNING

Built-in does not mean verified support. Unless a provider is explicitly promoted in the compatibility docs, treat it as unverified.

Built-in CLI Providers

Agent	Command	Verification	Description
Claude Code	adhdev launch claude	Partial	Anthropic's Claude coding agent
Gemini CLI	adhdev launch gemini	Unverified	Google's Gemini AI in terminal
Codex CLI	adhdev launch codex	Partial	OpenAI's Codex terminal agent
Aider	adhdev launch aider	Unverified	Pair-programming CLI for repo editing
Cursor CLI	adhdev launch cursor-cli	Unverified	Cursor's terminal agent workflow
GitHub Copilot CLI	adhdev launch github-copilot-cli	Unverified	GitHub Copilot's terminal interface
Goose CLI	adhdev launch goose	Unverified	Block's Goose coding agent
OpenCode CLI	adhdev launch opencode	Unverified	Open-source terminal coding agent

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. Among the current public promotions, Claude Code and Codex CLI have the clearest evidence.

Launching a CLI Agent

# Strong default paths
adhdev daemon
adhdev launch claude
adhdev launch gemini
adhdev launch codex

# Additional built-in CLI providers
adhdev launch aider
adhdev launch cursor-cli
adhdev launch github-copilot-cli
adhdev launch goose
adhdev launch opencode

Before 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.

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-duplicates

This 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 Notifications	Notify when approval is needed
Long Generation Alert	Warn when a turn runs too long
Long Generation Threshold	Threshold in seconds (30–600)

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

Next Steps

• Getting Started →
• ACP Agents →
• MCP Server →
• Compatibility & Caveats →
• Troubleshooting →
• Provider Issues →