3.8 KiB
Agents
Agents are the AI processes that OpenACP connects you to. Each agent implements the Agent Client Protocol (ACP) and exposes a prompt interface. OpenACP manages spawning, communication, and lifecycle.
Browsing available agents
Use /agents to see what is installed and what is available to install:
/agents
The response has two sections:
- Installed — agents ready to use, with a checkmark
- Available to install — agents from the registry, with install buttons
The available list is paginated (6 per page) with Prev/Next navigation. Agents marked with a warning icon have unmet dependencies — tap the warning to see what is missing.
The registry is fetched from cdn.agentclientprotocol.com and cached locally for 24 hours.
Installing an agent
From the /agents list, tap the install button next to any agent. Or use the command directly:
/install claude
/install gemini
/install codex
Progress updates appear in-line as the installation runs — downloading, extracting, configuring. After success, a button lets you start a session with the new agent immediately.
Some agents require additional setup after installation. Setup steps appear as copyable commands, for example:
Install Claude CLI: npm install -g @anthropic-ai/claude-code
Login: claude login (opens browser)
Uninstalling an agent
Agents can be uninstalled from the CLI (see CLI Commands for the full command reference):
openacp agents uninstall <name>
This removes the agent's binary and configuration from ~/.openacp/agents/. Any existing sessions using that agent are not affected until they end.
Switching agent per session
Pass the agent name to /new to use a specific agent for a session:
/new claude
/new gemini ~/code/my-project
If you have only one agent installed, it is selected automatically.
Default agent
The default agent is used when you create a session without specifying one. Configure it in ~/.openacp/config.json:
{
"defaultAgent": "claude"
}
Or use /settings to change it in-chat.
Agent types
Agents are distributed in four ways:
| Type | Description | Example |
|---|---|---|
npx |
Runs via Node.js package runner | npx @anthropic-ai/claude-code |
uvx |
Runs via Python package runner (uv) | uvx goose |
binary |
Platform-specific binary download | codex |
custom |
User-defined command and arguments | Any local tool |
OpenACP detects which distribution method is appropriate for your platform and handles installation automatically. If a required runtime (node, npx, uv, uvx) is missing, the agent shows as unavailable with an install hint.
Popular agents
| Agent | Distribution | Notes |
|---|---|---|
| Claude (claude-code) | npx | Requires Anthropic API key or Claude login |
| Gemini CLI | npx | Requires Google AI API key |
| Codex CLI | binary | Requires OpenAI API key |
| Goose | uvx | Requires Python / uv |
Use /agents for the current full list — the registry is updated independently of OpenACP releases.
Agent capabilities
Some agents declare capabilities that OpenACP uses to enable features:
- Audio — If an agent supports native audio input, voice attachments are passed directly rather than transcribed
- Commands — Agents can publish a list of slash commands that appear as skill shortcuts in the session topic
Capabilities are detected automatically when a session starts.
Custom agents
You can add a custom agent directly to your config without going through the registry:
{
"agents": {
"my-agent": {
"command": "node",
"args": ["/path/to/my-agent.js"],
"workingDirectory": "~/code",
"env": {
"MY_API_KEY": "..."
}
}
}
}
The agent must implement the ACP protocol to communicate with OpenACP.