Skip to main content
The happy acp command runs any agent that implements the Agent Client Protocol (ACP), providing a generic interface for AI agent integration.

​
Syntax

happy acp <agent-name> [options]
happy acp -- <command> [args]

​
Description

The ACP (Agent Client Protocol) command provides a unified interface for running various AI agents through Happy’s infrastructure. It supports:
  • Known ACP-compatible agents (gemini, opencode)
  • Custom ACP commands
  • Permission management
  • Mobile control integration
  • Session persistence
ACP is developed by Zed Industries and provides a standardized protocol for agent communication.

​
Arguments

​
agent-name
string
Name of a known ACP agent to run. Currently supported:
  • gemini - Google Gemini agent
  • opencode - OpenCode agent
​
command
string
Custom ACP-compatible command to execute (use with -- separator)

​
Options

​
--started-by
string
Session origin. Options: daemon or terminal. Internal use
​
--verbose
flag
Print raw ACP backend and envelope events for debugging
happy acp opencode --verbose
​
--
separator
Separates Happy options from the custom ACP command. Everything after -- is treated as the agent command
happy acp -- opencode --acp

​
Known Agents

​
Gemini

happy acp gemini
Runs Google Gemini through the generic ACP interface. This is equivalent to happy gemini but uses the ACP protocol layer.
For Gemini, we recommend using happy gemini directly for the best experience with Gemini-specific features.

​
OpenCode

happy acp opencode
Runs the OpenCode agent through ACP.

​
Examples

​
Run Known Agent

happy acp gemini
Starts Gemini using the ACP protocol.

​
Run Custom ACP Command

happy acp -- opencode --acp
Executes a custom command that implements the ACP protocol. The -- separator tells Happy that everything after it is part of the agent command.

​
Verbose Mode

happy acp opencode --verbose
Shows detailed ACP protocol events: 
[10:30] Incoming user message: "Help me refactor this code"
[10:30] Tool: read_file started (callId=call_1)
[10:30] Tool: read_file completed (callId=call_1)
[10:30] Outgoing message: "I'll help you refactor..."

​
Custom Agent with Arguments

happy acp -- my-custom-agent --model gpt-4 --temperature 0.7
Runs a custom ACP agent with specific parameters.

​
Output

​
Standard Mode

In standard mode, you see cleaned-up messages: 
[10:30] User: Help me refactor this function
[10:30] Assistant: I'll help you refactor that function...
[10:30] Tool: read_file started
[10:30] Tool: read_file completed
[10:30] Assistant: Here's the refactored version...

​
Verbose Mode

With --verbose, you see raw ACP events: 
[10:30] Incoming user message: "Help me refactor this function"
[10:30] Tool: read_file started (callId=call_abc123)
[10:30] [Raw] {"type":"tool_call_start","id":"call_abc123",...}
[10:30] Tool: read_file completed (callId=call_abc123)
[10:30] [Raw] {"type":"tool_call_end","id":"call_abc123",...}
[10:30] Outgoing message: "I'll help you..."

​
ACP Protocol

The Agent Client Protocol (ACP) is a standardized protocol for AI agent communication. It defines:
  • Message format for agent communication
  • Tool calling conventions
  • Permission request/response flow
  • Session state management
  • Configuration options

​
Protocol Events

Common ACP events you might see with --verbose: 
{
  "type": "user_message",
  "message": "Help me with this code"
}

​
Creating Custom ACP Agents

To create your own ACP-compatible agent:
  1. Implement the ACP protocol in your agent
  2. Ensure it accepts standard ACP messages
  3. Output ACP-formatted events
  4. Run it through Happy:
happy acp -- /path/to/your-agent --acp
Happy will handle:
  • Session management
  • Mobile connectivity
  • Permission handling
  • State synchronization

​
Configuration

​
Agent-Specific Config

Each agent may have its own configuration. For example, Gemini through ACP uses:
  • ~/.gemini/config.json - Model and project settings
  • ~/.gemini/oauth_creds.json - Authentication tokens

​
Happy Config

Happy’s ACP integration respects:
  • Sandbox settings from happy sandbox configure
  • Permission modes from mobile app
  • Session metadata and state

​
Session Management

​
Mode Changes

When permission mode or model changes, Happy automatically:
  1. Stops the current agent session
  2. Preserves conversation context
  3. Restarts with new settings
  4. Resumes with full history

​
Remote Control

Control ACP agents from your mobile device:
  • Send prompts and receive responses
  • Change permission modes
  • Abort or kill sessions
  • Monitor tool executions

​
Troubleshooting

​
Agent Not Found

If you see “Unknown ACP agent”: 
# Check known agents
happy acp gemini  # Use known agent name

# Or use custom command with --
happy acp -- /full/path/to/agent

​
Protocol Errors

If the agent fails with protocol errors: 
# Enable verbose mode to see raw events
happy acp opencode --verbose

# Check logs
happy doctor

​
Authentication Issues

Ensure you’re authenticated: 
happy auth status
And that vendor tokens are connected: 
happy connect status

​
Debug Mode

Enable full debugging: 
DEBUG=* happy acp gemini --verbose
Logs will be written to ~/.happy/logs/.

​
Performance Considerations

​
Verbose Mode Impact

Using --verbose adds overhead from:
  • Console output formatting
  • Event serialization
  • Additional logging
Use it only for debugging, not production sessions.

​
Agent Restarts

Mode changes trigger agent restarts. To minimize restarts:
  • Set permission mode once at session start
  • Avoid frequent model changes
  • Use consistent configuration

​
Advanced Usage

​
Chaining with Other Tools

# Pipe agent output to file
happy acp -- my-agent --output json > results.json

# Use with environment variables
MY_VAR=value happy acp -- my-agent

​
Custom MCP Servers

ACP agents can use Happy’s MCP server for enhanced capabilities:
  • Access to session metadata
  • Mobile device communication
  • Permission management
The MCP server is automatically provided to all ACP agents.

​
Protocol Specification

For the full ACP specification, see: The protocol is maintained by Zed Industries and uses the official @agentclientprotocol/sdk package.
The acp command provides a generic interface. For the best experience with specific agents, use their dedicated commands (e.g., happy gemini instead of happy acp gemini).