Agents (ACP + HTTP)

ACP (Agent Client Protocol)

For agents that run as local processes. Uses JSON-RPC 2.0 over stdin/stdout.

Claude Setup

To use Claude with Hash, install the ACP adapter. It bundles the Claude Agent SDK, so there is nothing else to install:

Using an API key? Set ANTHROPIC_API_KEY in your environment (e.g., in ~/.hashrc). Already logged into the Claude Code CLI with a subscription? No further setup needed on macOS.

Upgrading from an older Hash? The previous adapter package @zed-industries/claude-code-acp has been renamed to @agentclientprotocol/claude-agent-acp, and the executable is now claude-agent-acp (was claude-code-acp). Update your command in config.toml accordingly.

Gemini CLI Setup

Google's Gemini CLI supports ACP natively with an experimental flag. First, install the Gemini CLI:

Then configure Hash to use Gemini with the --experimental-acp flag:

Alternatively, you can use: command = "gemini --experimental-acp"

When to use ACP

• Claude Code, Gemini CLI, or any tool with ACP support
• You want the agent to have full context (files, git, etc.)
• Session persistence matters

Behavior

• Lazy connect: connects on first ?? use
• One session per shell instance
• Conversation follow-ups reuse the same ACP session, so the agent keeps its context between turns
• Closed on shell exit

Selecting a model

ACP agents can advertise the models they support over the protocol. When they do, Hash shows which one is active and lets you switch between them, no restart required. Your choice sticks for the rest of the shell session.

See the active model

The agent status line shows the current model in square brackets while it works:

When the agent reports no model (some stdio agents, or the HTTP transport), the brackets are simply omitted.

List and switch with model

Run the built-in model command with no arguments to open an interactive picker:

Prefer to skip the picker? Select or list directly:

Good to know

• The selection lasts for the current shell session and is re-applied automatically if the agent reconnects.
• Model listing is ACP-only. With the HTTP transport the model is fixed by model in your config.
• If an agent exposes no model option, model tells you so and the status line shows no brackets.
• Turn the command off with disable_builtins = ["model"] under [shell].

HTTP transport

For Ollama-style HTTP model servers. Hash sends an Ollama /api/generaterequest shape and reads the response field.

HTTP agents are stateless, so conversation follow-ups include a compact transcript of the previous turns instead of reusing a session.

When to use HTTP

• Ollama or compatible local model servers
• Self-hosted inference
• You want full control over the model

Named agents

Use [agent.<name>] tables when you want to keep multiple agent definitions in one config and switch with [agent].default.

Agent config options

Debug checklist

Check the agent command works directly in your terminal before configuring it in Hash.