CLI adapters
By default, agents send prompts to LLM providers via HTTP API. CLI adapters instead spawn an external tool as a subprocess — the tool handles its own model calls, tool execution, and reasoning. Use them when the agent needs to operate on files in a codebase.
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
| Adapter Type | CLI Tool | Best For |
|---|---|---|
claude_local | Claude Code (claude) | Coding, file operations, shell commands |
codex_local | OpenAI Codex CLI (codex) | Coding with OpenAI models |
gemini_local | Gemini CLI (gemini) | Coding with Google models |
process | Any shell command | Custom tools, scripts |
Setting up Claude Code
Prerequisites
- Install Claude Code:
npm install -g @anthropic-ai/claude-code - Authenticate:
claude login(or setANTHROPIC_API_KEYenv var) - Verify:
claude --version
Configuration
- Go to Agents → Edit for the agent you want to route through Claude Code
- Scroll to the CLI Adapter section
- Set Adapter Type to “Claude Code (Local CLI)”
- Set Default Workspace Base (e.g.,
C:\projects) - Optionally set CLI Model Override (e.g.,
claude-sonnet-4-6) - Save
Workspace resolution
When an agent with a CLI adapter works on an issue, the working directory is resolved in this order:
| Priority | Source | Example |
|---|---|---|
| 1 (highest) | Project workspace path | C:\projects\my-saas-app |
| 2 | Agent base + project name | C:\projects\ + my-saas-app |
| 3 (fallback) | Global default | ~/.exolvra/workspaces/my-saas-app |
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.
Configuration for Claude Max users
With Claude Max (unlimited usage), cost isn’t a factor. Here’s the optimal setup:
Recommended agent configuration
| Agent | Adapter | Model override | Workspace base | Rationale |
|---|---|---|---|---|
| Code Assistant | claude_local | claude-sonnet-4-6 | C:\projects | Full codebase access, file editing, shell |
| DevOps Engineer | claude_local | claude-sonnet-4-6 | C:\projects | Infrastructure code, deployment scripts |
| System Administrator | claude_local | claude-sonnet-4-6 | — | Shell access for system operations |
| Research Analyst | API (default) | claude-sonnet-4-6 | — | Needs web search, data store, file store |
| Data Analyst | API (default) | claude-sonnet-4-6 | — | Needs data store, web tools |
| Creative Writer | API (default) | claude-sonnet-4-6 | — | Needs data store, memory |
| Project Manager | API (default) | claude-sonnet-4-6 | — | Needs project, issue, and goal tools |
| Home Assistant | API (default) | claude-haiku-4-5 | — | Quick responses, low complexity |
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 (Claude Code has 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:
- A Research Analyst (API) researches best practices and saves findings to the data store
- The Project Manager (API) creates implementation issues from the research findings
- A Code Assistant (Claude Code CLI) 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
| Setting | Default | Description |
|---|---|---|
| Timeout (seconds) | 900 (15 min) | Max execution time before termination |
| Grace (seconds) | 15 | Time between graceful and forced shutdown |
| Max turns per run | 300 | Claude Code’s agentic turn limit |
| Skip permissions | false | Bypass Claude Code’s permission prompts |
| Environment variables | {} | Extra env vars injected into the CLI process |
Skip permissions for autonomous execution
By default, Claude Code prompts for permission before file writes and shell commands. For autonomous agent execution, enable Skip Permissions on the agent edit page. This passes --dangerously-skip-permissions to Claude Code.
Warning. Only enable this for trusted, well-scoped projects. The agent will execute shell commands without confirmation.
Custom CLI model
Override the model Claude Code uses by setting CLI Model Override:
claude-opus-4-6— highest quality, slowestclaude-sonnet-4-6— best balance (recommended)claude-haiku-4-5— fastest, cheapest (good 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:
ANTHROPIC_API_KEY— override the API key for this agentCLAUDE_CODE_MAX_TURNS— override max turns- 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:
- Set Adapter Type to “Process (Custom Command)”
- Set Command to the CLI invocation (e.g.,
python my_agent.py) - The prompt is passed via stdin
- 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 the gateway 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}.
Claude Code 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 Claude Code’s own permission list.