CLI adapters

When to use CLI adapters

Reach for a CLI adapter when:

• The agent needs to read, edit, and create files in a real codebase
• The external tool has superior capabilities for the task (e.g., Claude Code for coding)
• You have an unlimited plan (Claude Max, Codex Pro) and cost isn’t a factor

Stick with the default API path when:

• The agent needs Exolvra’s built-in tools (data store, task board, project management, web search, memory)
• You want agent output visible in the dashboard as comments, data entries, and task updates
• You need budget tracking and execution monitoring

Supported adapters

Setting up a CLI adapter

The steps are the same for every CLI tool — install the binary, authenticate it once on the host, then point an agent at it. Claude Code is used as the worked example below; for Codex CLI (codex) or Gemini CLI (gemini) the dashboard steps are identical, just with that tool’s own binary, login, and model ids.

Prerequisites

1. Install the CLI tool and put its binary on PATH. For Claude Code: npm install -g @anthropic-ai/claude-code. (Codex and Gemini CLI ship their own installers.)
2. Authenticate it once on the host — claude login, codex login, or gemini auth — or set the tool’s API-key env var.
3. Verify it runs from a shell (e.g., claude --version).

Configuration

1. Go to Agents → Edit for the agent you want to route through the CLI
2. Scroll to the CLI Adapter section
3. Set Adapter Type to the tool you installed — “Claude Code (Local CLI)”, “Codex (Local CLI)”, or “Gemini (Local CLI)”
4. Set Default Workspace Base (e.g., C:\projects)
5. Optionally set CLI Model Override (the model id belongs to that tool’s provider — e.g., a Claude id for Claude Code, an OpenAI id for Codex)
6. Save

Workspace resolution

When an agent with a CLI adapter works on an issue, the working directory is resolved in this order:

Set the project workspace path on the project edit page. This means the same agent working on different projects automatically runs in the correct directory.

Example: a coding team on an unlimited plan

If you’re on an unlimited CLI plan (Claude Max, Codex Pro, or similar), cost isn’t a factor and you can route the file-touching agents through the CLI. Here’s one worked split. The adapter ids and model overrides below use Claude Code as the example; swap in codex_local/gemini_local and that provider’s model ids if you’ve standardized on a different CLI.

Example agent configuration

Why keep some agents on API?

CLI adapters have their own tool set and don’t use Exolvra’s tools. This means:

CLI adapter agents can read, write, and edit files in the workspace; run shell commands; search the web (some CLI tools, such as Claude Code, ship built-in web search); reason deeply about code and architecture; create files, run tests, and commit code.

CLI adapter agents cannot save to Exolvra’s data store, update the task board, create issues or update goals, send messages to other agents via Exolvra, use Exolvra’s memory system, or trigger runbooks and workflows.

Rule of thumb. If the agent’s work product should be in the codebase (files, code changes, configs) → use a CLI adapter. If it should be in the dashboard (research findings, task tracking, project management) → use the API path.

Hybrid approach: research → code handoff

For tasks that span research and implementation:

1. A Research Analyst (API) researches best practices and saves findings to the data store
2. The Project Manager (API) creates implementation issues from the research findings
3. A Code Assistant (any CLI adapter — Claude Code, Codex, or Gemini) implements the code changes in the repo

The PM naturally bridges the gap — it reads the research from the data store and creates issues that the Code Assistant picks up and executes in the workspace.

Advanced configuration

Adapter settings

Skip permissions for autonomous execution

By default, most CLI tools prompt for permission before file writes and shell commands. For autonomous agent execution, enable Skip Permissions on the agent edit page — Exolvra passes the tool’s bypass flag (for Claude Code that’s --dangerously-skip-permissions).

Warning. Only enable this for trusted, well-scoped projects. The agent will execute shell commands without confirmation.

Custom CLI model

Override the model the CLI tool uses by setting CLI Model Override. The id has to be one that tool’s provider recognizes — a Claude id for Claude Code, an OpenAI id for Codex, a Gemini id for Gemini CLI. As a rule of thumb each provider offers a high-quality/slow tier, a balanced tier (usually the right default), and a fast/cheap tier for simple tasks.

This is separate from Exolvra’s default model — it only affects the CLI adapter.

Environment variables

Inject environment variables into the CLI process. The variable names belong to whichever tool you’re running — for Claude Code that’s ANTHROPIC_API_KEY and CLAUDE_CODE_MAX_TURNS; Codex and Gemini CLI read their own (OPENAI_API_KEY, GEMINI_API_KEY, etc.):

• The tool’s API-key var — override the key for this agent
• The tool’s max-turns var — override the agentic turn limit
• Custom project-specific vars (e.g., DATABASE_URL, AWS_PROFILE)

Set them via the Environment Variables section on the agent edit page (key=value pairs).

Process adapter (custom tools)

The process adapter type lets you use any CLI tool:

1. Set Adapter Type to “Process (Custom Command)”
2. Set Command to the CLI invocation (e.g., python my_agent.py)
3. The prompt is passed via stdin
4. Output is read from stdout

This enables integration with any AI tool that accepts text input and produces text output.

Troubleshooting

Agent not using CLI adapter. Verify the adapter type is set (not “API”). Check that the CLI tool is installed and on PATH. Check Exolvra’s logs for “CLI adapter” messages.

Wrong working directory. Check the project’s workspace path (highest priority). Check the agent’s default workspace base. The fallback is ~/.exolvra/workspaces/{project-name}.

CLI adapter timeout. Increase the Timeout setting (default 900s = 15 minutes). For large codebases, 1800s (30 min) may be needed. Check if the task is too broad and split it into smaller issues.

Permission prompts blocking execution. Enable “Skip Permissions” on the agent edit page, or pre-approve tools via the CLI tool’s own permission list.