Java Library for Agent Client Protocol (ACP)

The Agent Client Protocol (ACP) is an open standard for communication between clients and AI coding agents. It defines a JSON-RPC 2.0-based protocol over stdio that lets clients initialize sessions, send prompts, receive streamed updates (thoughts, messages, tool calls, plans), and manage the agent lifecycle.

This project is a Java library for ACP, built with standard java.util.concurrent APIs (CompletableFuture, ScheduledExecutorService) for async operations and Jackson for JSON processing. It provides both synchronous and asynchronous APIs to interact with any ACP-compatible agent (e.g. OpenCode) using stdio.

The project implements the ACP Schema Specification v1. The JSON schema definition is bundled at schema/src/main/resources/schema/acp/v1/schema.json and Java records are generated from it using JSonSchemaGenerator (a custom code generator included in the schema module). See CONTRIBUTING.md for details on regenerating schema classes.

Project structure

The project is organized as a multi-module Maven build:

Module	Artifact ID	Description
`schema`	`acp-schema`	ACP JSON Schema (`v1`), generated Java records/enums, and `JSonSchemaGenerator` code generator
`core`	`acp-core`	ACP implementation library: `AcpClient`, `AcpAsyncClient`, `AcpSyncClient`, stdio transport. Depends on `schema`
`client`	`acp-client`	Picocli CLI (`AcpAgentCommand`), skills, and sandbox. Depends on `core`. Built as Quarkus uber-jar

Prerequisites

JDK 21+
Apache Maven 3.9+
Any ACP-compatible agent (see Agents and providers for the list of some agents and how to install them)
(Optional) JBang for running the CLI via catalog

Build

Compile the project and build the uber-jar:

mvn clean install

The uber-jar is produced at client/target/acp-client-0.1.0-SNAPSHOT-runner.jar.

Usage

Running with `java -jar`

# Default prompt: "Say Hello" with OpenCode agent
java -jar client/target/acp-client-0.1.0-SNAPSHOT-runner.jar

# Custom prompt
java -jar client/target/acp-client-0.1.0-SNAPSHOT-runner.jar --prompt "What is 6+6?"

# With a specific agent, provider, and model
java -jar client/target/acp-client-0.1.0-SNAPSHOT-runner.jar \
  --agent claude \
  --provider vertex-ai \
  --model claude-opus-4-6 \
  --prompt "Say hello"

Running with JBang

A JBang catalog is provided at the project root and that you can use when you develop/test. After building:

# Run from the project root using the local catalog and uber jar generated under client/target/ !
jbang acp-client --prompt "What is 6+6?"

If you plan to use the tool outside of this project, then install it using the maven GAV

jbang app install --name acp-client io.quarkiverse.ai:acp-java-client:0.1.0-SNAPSHOT:runner

cd /java/project/to/code/using/ai
acp-client --prompt "Say hello"

The command supports to generate the autocompletion bash script:

source <(acp-client generate-completion)

Running with Quarkus dev mode

mvn quarkus:dev -pl client -Dquarkus.args="--prompt 'Say Hello'"

Example output

11:11:57,492 INFO  [StdioAcpClientTransport] ACP agent starting
11:11:57,522 INFO  [StdioAcpClientTransport] ACP agent started
11:11:58,435 INFO  [AcpAgentCommand] Connected to the ACP agent: OpenCode - v1.15.4
11:11:58,613 INFO  [AcpAgentCommand] Session created: ses_1b631ae8bffegMSoAYKMCI6cUc
11:11:58,619 INFO  [AcpAgentCommand] [Commands] Available:
11:11:58,622 INFO  [AcpAgentCommand] Model: opencode/big-pickle
11:11:58,623 INFO  [AcpAgentCommand] Sending prompt: Say Hello
Here is the AI response:
Hello
11:12:00,661 INFO  [AcpAgentCommand] [Usage] used=8081 size=200000 cost={amount=0, currency=USD}
11:12:00,665 INFO  [AcpAgentCommand] Done! Stop reason: END_TURN
11:12:00,676 INFO  [StdioAcpClientTransport] ACP agent process stopped (exit code 143)

CLI options

All options support environment variable fallback. Precedence: CLI argument > environment variable > default value.

Option	Env Variable	Description	Default
`-a`, `--agent`	`ACP_AGENT`	ACP agent: `opencode`, `claude`, `pi`, `gemini`	`opencode`
`-p`, `--prompt`	`ACP_PROMPT`	The prompt text to send to the agent	`Say Hello`
`--provider`	`ACP_PROVIDER`	Provider: `zen`, `vertex-ai`	`zen`
`-m`, `--model`	`ACP_MODEL`	The model to use, e.g. `claude-opus-4-6` (resolved per agent/provider)
`--agent-binary`	`ACP_AGENT_BINARY`	Override agent binary path (for custom agents)
`--agent-args`	`ACP_AGENT_ARGS`	Override agent arguments (for custom agents)
`--request-timeout`	`ACP_REQUEST_TIMEOUT`	Timeout in seconds for steps: initialize, create session, etc.	`30`
`--prompt-timeout`	`ACP_PROMPT_TIMEOUT`	Timeout in seconds for prompt requests; 0 means no timeout	`0`
`--permission-mode`	`ACP_PERMISSION_MODE`	How to respond to agent permission requests (see below)	`allow_always`
`-l`, `--log-level`	`ACP_LOG_LEVEL`	Log level: `INFO`, `DEBUG`, `TRACE`, `WARNING`, `SEVERE`	`INFO`
`-h`, `--help`		Show help message and exit
`-V`, `--version`		Print version info and exit

The --agent option resolves the binary and arguments automatically from a built-in registry. For custom or unsupported agents, use --agent-binary and --agent-args instead.

When using --agent opencode with --provider vertex-ai, simple model names are resolved automatically: --model claude-opus-4-6 becomes google-vertex-anthropic/claude-opus-4-6@default.

Examples

# OpenCode with Zen (default agent + provider)
acp-client --prompt "Say Hello"

# Claude Code with Vertex AI
acp-client --agent claude --provider vertex-ai --model claude-opus-4-6 \
  --prompt "Say Hello"

# Using environment variables
export ACP_AGENT=claude
export ACP_PROVIDER=vertex-ai
export ACP_MODEL=claude-opus-4-6
acp-client --prompt "Execute the java-project-discovery skill."

# Gemini CLI
acp-client --agent gemini --prompt "Say Hello"

# Custom agent binary
acp-client --agent-binary my-agent --agent-args "serve" --prompt "Say Hello"

Agents and providers

ACP agents

The following ACP-compatible agents can be used with this client. Install the agent you need and pass its binary and args via the --agent-binary and --agent-args CLI options.

Agent	Binary (`--agent-binary`)	Args (`--agent-args`)	Installation
OpenCode	`opencode`	`acp`	See OpenCode ACP docs
Claude Code	`claude-agent-acp`		`npm install -g @agentclientprotocol/claude-agent-acp` (docs)
Pi	`pi-acp`		`npm install -g pi-acp` (docs)
Gemini CLI	`gemini`	`--acp`	`npm install -g @google/gemini-cli` (docs)

Providers

Each agent can be configured with a model provider. The --provider option controls which environment variables are validated before connecting. The client will exit with an error if any required variable is missing.

Agent	Provider (`--provider`)	Environment variables	Documentation
OpenCode	`zen` (default)	none	OpenCode Zen
OpenCode	`vertex-ai`	`GOOGLE_APPLICATION_CREDENTIALS`, `VERTEX_LOCATION`, `GOOGLE_CLOUD_PROJECT`	Google Vertex AI
Claude Code	`vertex-ai`	`ANTHROPIC_VERTEX_PROJECT_ID`, `ANTHROPIC_MODEL`, `CLAUDE_CODE_USE_VERTEX`, `CLOUD_ML_REGION`	Anthropic Vertex AI
Pi	`vertex-ai`	`GOOGLE_APPLICATION_CREDENTIALS`, `GOOGLE_CLOUD_PROJECT`, `CLOUD_ML_REGION`	pi-vertex-claude
Gemini CLI	`vertex-ai`	`GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`	Gemini CLI ACP mode

Permissions

When an agent needs to perform a sensitive operation (e.g. writing a file, running a command), it sends a session/request_permission request. The client responds automatically based on the --permission-mode value:

Mode	Behavior
`allow_always`	Accept and remember the choice (default)
`allow_once`	Accept only this time
`reject_once`	Reject only this time
`reject_always`	Reject and remember the choice

Example:

java -jar client/target/acp-client-0.1.0-SNAPSHOT-runner.jar \
  --permission-mode allow_once \
  --prompt "Create a Java HelloWorld class"

Logging

The project uses Quarkus logging (backed by JBoss Log Manager). By default, only INFO-level messages are shown (connection status, prompt lifecycle). Session update details (thoughts, tool calls, plans, commands, usage) and protocol internals are logged at DEBUG or TRACE level.

Log levels are configured in client/src/main/resources/application.properties. You can also override them on the command line:

# Enable debug logging
java -Dquarkus.log.category.\"io.quarkiverse\".level=DEBUG \
  -jar client/target/acp-client-0.1.0-SNAPSHOT-runner.jar \
  --prompt "Say Hello"

# Enable trace logging (raw JSON-RPC messages)
java -Dquarkus.log.category.\"io.quarkiverse\".level=TRACE \
  -jar client/target/acp-client-0.1.0-SNAPSHOT-runner.jar \
  --prompt "Say Hello"

Log levels

Level	What you see
`INFO` (default)	Connected to agent, sending prompt, stop reason
`DEBUG`	+ agent thoughts, tool calls, plans, commands, mode changes, usage, capabilities, session ID
`TRACE`	+ raw JSON-RPC messages sent/received by the transport

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Java Library for Agent Client Protocol (ACP)

Project structure

Prerequisites

Build

Usage

Running with `java -jar`

Running with JBang

Running with Quarkus dev mode

Example output

CLI options

Examples

Agents and providers

ACP agents

Providers

Permissions

Logging

Log levels

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Java Library for Agent Client Protocol (ACP)

Project structure

Prerequisites

Build

Usage

Running with java -jar

Running with JBang

Running with Quarkus dev mode

Example output

CLI options

Examples

Agents and providers

ACP agents

Providers

Permissions

Logging

Log levels

Running with `java -jar`