ACP — Agent Client Protocol for Crystal

An unofficial Crystal implementation of the Agent Client Protocol (ACP), which defines a JSON-RPC 2.0 based communication standard between code editors (clients) and AI coding agents.

Features

• Full ACP Protocol Support — Initialize, authenticate, create sessions, send prompts, handle streaming updates, and manage permissions.
• JSON-RPC 2.0 Compliant — Proper request/response correlation, notification handling, and error codes (including ACP-specific codes like AUTH_REQUIRED and RESOURCE_NOT_FOUND).
• Stdio Transport — Newline-delimited JSON over stdin/stdout pipes to a spawned agent process.
• Async Architecture — Background dispatcher fiber routes incoming messages via Crystal channels.
• Streaming Updates — Real-time handling of agent message chunks, tool calls, thoughts, plans, slash commands, mode changes, and config option updates.
• Permission Handling — Built-in support for session/request_permission agent-initiated requests.
• Typed Client Method Handlers — Register strongly-typed handlers for fs/read_text_file, fs/write_text_file, and all terminal/* methods with automatic JSON deserialization.
• Protocol Enums — Strongly-typed enums for StopReason, ToolKind, ToolCallStatus, PermissionOptionKind, PlanEntryPriority, PlanEntryStatus, SessionConfigOptionCategory, and Role.
• Tool Call Content Types — Typed structs for tool call content variants: standard content blocks, file diffs (ToolCallDiff), and embedded terminals (ToolCallTerminal), plus ToolCallLocation for file tracking.
• Type-Safe — All protocol types use JSON::Serializable with discriminated unions for polymorphic content.
• Zero External Dependencies — Uses only the Crystal standard library.
• Ergonomic API — High-level Session wrapper and PromptBuilder DSL on top of the low-level Client.

Installation

Add the dependency to your shard.yml:

dependencies:
  acp:
    github: hahwul/acp

Then run:

shards install

Quick Start

require "acp"

# 1. Connect to an agent process via stdio
transport = ACP::ProcessTransport.new("my-agent", ["--stdio"])
client = ACP::Client.new(transport, client_name: "my-editor")

# 2. Initialize the connection (handshake)
init_result = client.initialize_connection

# 3. Create a new session
session = ACP::Session.create(client, cwd: Dir.current)

# 4. Handle streaming updates
client.on_update = ->(update : ACP::Protocol::SessionUpdateParams) do
  case u = update.update
  when ACP::Protocol::AgentMessageChunkUpdate
    print u.text  # Stream agent text to the terminal
  when ACP::Protocol::ToolCallUpdate
    puts "\n🔧 #{u.title} [#{u.status}]"
  when ACP::Protocol::AgentThoughtChunkUpdate
    puts "💭 #{u.text}"
  end
  nil
end

# 5. Send a prompt and wait for the result
result = session.prompt("Explain this codebase in one paragraph.")
puts "\n[Done — stop reason: #{result.stop_reason}]"

# 6. Clean up
client.close

Examples

Several examples are provided in the examples/ directory to help you get started:

• simple_client.cr — A minimal example showing basic connection and prompting.
• content_blocks.cr — Demonstrates rich prompts with multiple content types (text, resource links) and tool handling.
• gemini_agent.cr — Demonstrates how to use the Gemini CLI as an ACP agent.
• interactive_client.cr — A full-featured interactive CLI client with streaming, tool calls, and permission handling.

Running Examples

# Basic usage
crystal run examples/simple_client.cr -- <agent-command>

# Using Gemini CLI as an agent
# Requires: gemini CLI installed and GEMINI_API_KEY environment variable
crystal run examples/gemini_agent.cr

# Rich prompt example
crystal run examples/content_blocks.cr -- my-agent --stdio

Architecture

┌─────────────────────────────────────────────────────────┐
│                      Your Application                   │
│                                                         │
│  ┌───────────┐   ┌─────────────┐   ┌────────────────┐   │
│  │  Session  │──▶│   Client    │──▶│   Transport    │───┼──▶ Agent Process
│  │  (high)   │   │  (core)     │   │  (stdio/pipe)  │   │     (stdin/stdout)
│  └───────────┘   └─────────────┘   └────────────────┘   │
│       │               │                    │            │
│       ▼               ▼                    ▼            │
│  PromptBuilder   Dispatcher Fiber    Reader Fiber       │
│                  (routes msgs)       (parses JSON)      │
└─────────────────────────────────────────────────────────┘

Module Overview

API Reference

ACP::Client

The main class for communicating with an ACP agent.

Constructor

client = ACP::Client.new(
  transport,                          # ACP::Transport instance
  client_name: "my-app",             # Sent during initialize
  client_version: "1.0.0",           # Sent during initialize
  client_capabilities: ACP::Protocol::ClientCapabilities.new(
    fs: ACP::Protocol::FsCapabilities.new(
      read_text_file: true,
      write_text_file: true,
    ),
    terminal: false
  )
)

Lifecycle Methods

# Perform the ACP handshake. Must be called first.
init_result = client.initialize_connection
# => ACP::Protocol::InitializeResult

# Authenticate (if agent requires it).
client.authenticate("oauth")

# Create a new session.
result = client.session_new("/path/to/project")
# => ACP::Protocol::SessionNewResult

# Load a previous session (if agent supports loadSession capability).
result = client.session_load("session-id-from-before", "/path/to/project")
# => ACP::Protocol::SessionLoadResult

# Send a text prompt.
result = client.session_prompt_text("Hello, agent!")
# => ACP::Protocol::SessionPromptResult

# Send a prompt with content blocks.
blocks = [ACP::Protocol::TextContentBlock.new("Explain this:").as(ACP::Protocol::ContentBlock)]
result = client.session_prompt(blocks)

# Cancel the current operation.
client.session_cancel

# Change session mode.
client.session_set_mode("code")

# Change a session config option.
result = client.session_set_config_option("mode", "code")
# => ACP::Protocol::SessionSetConfigOptionResult

# Close the client and transport.
client.close

Callbacks

# Handle streaming updates from the agent.
client.on_update = ->(update : ACP::Protocol::SessionUpdateParams) do
  case u = update.update
  # ── ACP Standard Update Types ──
  when ACP::Protocol::UserMessageChunkUpdate
    print u.text  # During session/load replay
  when ACP::Protocol::AgentMessageChunkUpdate
    print u.text
  when ACP::Protocol::AgentThoughtChunkUpdate
    puts "💭 #{u.text}"
  when ACP::Protocol::ToolCallUpdate
    puts "🔧 #{u.title} [#{u.status}]"
  when ACP::Protocol::ToolCallStatusUpdate
    puts "🔧 #{u.tool_call_id} → #{u.status}"
  when ACP::Protocol::PlanUpdate
    u.entries.each { |e| puts "  #{e.status}: #{e.content}" }
  when ACP::Protocol::AvailableCommandsUpdate
    u.available_commands.each { |c| puts "  /#{c.name} — #{c.description}" }
  when ACP::Protocol::CurrentModeUpdate
    puts "Mode changed to: #{u.current_mode_id}"
  when ACP::Protocol::ConfigOptionUpdate
    puts "Config options updated"
  # ── Non-Standard Types (backward compat) ──
  when ACP::Protocol::AgentMessageStartUpdate
    # Agent message starting (non-standard)
  when ACP::Protocol::AgentMessageEndUpdate
    puts "" # Message complete (non-standard)
  when ACP::Protocol::StatusUpdate
    puts "⏳ #{u.status}: #{u.message}"
  when ACP::Protocol::ErrorUpdate
    STDERR.puts "❌ #{u.message}"
  end
  nil
end

# ── Typed Client Method Handlers (fs/*, terminal/*) ──
# Register these when advertising the corresponding capabilities.

# Handle fs/read_text_file requests from the agent.
client.on_read_text_file = ->(params : ACP::Protocol::ReadTextFileParams) do
  content = File.read(params.path)
  ACP::Protocol::ReadTextFileResult.new(content: content)
end

# Handle fs/write_text_file requests from the agent.
client.on_write_text_file = ->(params : ACP::Protocol::WriteTextFileParams) do
  File.write(params.path, params.content)
  ACP::Protocol::WriteTextFileResult.new
end

# Handle terminal/create requests from the agent.
client.on_create_terminal = ->(params : ACP::Protocol::CreateTerminalParams) do
  # ... spawn process, track terminal ...
  ACP::Protocol::CreateTerminalResult.new(terminal_id: "term_001")
end

# Other terminal handlers: on_terminal_output, on_release_terminal,
# on_wait_for_terminal_exit, on_kill_terminal

# Handle agent-initiated requests (e.g., permission prompts).
# This is the generic fallback for methods without typed handlers.
client.on_agent_request = ->(method : String, params : JSON::Any) do
  if method == "session/request_permission"
    # Return the user's choice using the ACP-spec outcome format
    JSON.parse(%({"outcome": {"outcome": "selected", "optionId": "allow-once"}}))
  else
    JSON.parse(%({}))
  end
end

# Handle non-update notifications.
client.on_notification = ->(method : String, params : JSON::Any?) do
  puts "Notification: #{method}"
  nil
end

# Handle disconnect.
client.on_disconnect = -> do
  puts "Connection lost!"
  nil
end

State Inspection

client.state                        # => ACP::ClientState (Created, Initialized, SessionActive, Closed)
client.closed?                      # => Bool
client.session_active?              # => Bool
client.session_id                   # => String?
client.agent_capabilities           # => ACP::Protocol::AgentCapabilities?
client.agent_info                   # => ACP::Protocol::AgentInfo?
client.auth_methods                 # => Array(JSON::Any)?
client.negotiated_protocol_version  # => UInt16?

ACP::Session

A higher-level wrapper that binds a Client to a specific session ID.

# Create via factory methods
session = ACP::Session.create(client, cwd: "/my/project")
session = ACP::Session.load(client, "previous-session-id", cwd: "/my/project")

# Send prompts — no need to pass session_id
result = session.prompt("What does this function do?")

# Send multi-block prompts
result = session.prompt([
  ACP::Protocol::TextContentBlock.new("Explain this file:"),
  ACP::Protocol::ResourceLinkContentBlock.from_path("/path/to/file.cr"),
].map(&.as(ACP::Protocol::ContentBlock)))

# Use the PromptBuilder DSL
result = session.prompt do |b|
  b.text("Explain this code:")
  b.file("/path/to/relevant_code.cr")
  b.resource("file:///path/to/file.py", "def hello(): pass", "text/x-python")
end

# Cancel, change mode, change config, inspect
session.cancel
session.set_mode("chat")
session.set_config_option("model", "model-2")
session.id                    # => "session-uuid"
session.available_mode_ids    # => ["code", "chat"]
session.closed?               # => false
session.close                 # Mark closed (client-side only)

ACP::PromptBuilder

Ergonomic DSL for constructing content block arrays.

builder = ACP::PromptBuilder.new
builder
  .text("Look at this code and image:")
  .file("/src/main.cr")                                   # Creates a resource_link
  .image("base64_encoded_data", "image/png")               # Base64 image data
  .image_data(base64_string, "image/jpeg")                 # Alias for image()
  .audio("base64_encoded_audio", "audio/wav")              # Base64 audio data
  .resource("file:///path/to/file.py", "code", "text/x-python")  # Embedded resource
  .resource_link("file:///doc.pdf", "doc.pdf", "application/pdf") # Resource link

blocks = builder.build  # => Array(ACP::Protocol::ContentBlock)

Content Block Types

These follow the ACP Content specification, which uses the same ContentBlock structure as MCP.

All content blocks inherit from ACP::Protocol::ContentBlock and are deserialized automatically via the "type" discriminator. FileContentBlock is a backward-compatible alias for ResourceLinkContentBlock.

Tool Call Content Types

Tool calls can produce three types of content, defined as typed structs inheriting from ACP::Protocol::ToolCallContent:

Additionally, ToolCallLocation tracks file locations with path : String and line : Int32? for "follow-along" features.

Protocol Enums

Strongly-typed enums for protocol constants (all serialize to/from their wire-format strings):

# Parse from wire string
reason = ACP::Protocol::StopReason.parse("end_turn")  # => StopReason::EndTurn
reason = ACP::Protocol::StopReason.parse?("unknown")   # => nil

# Use in comparisons
if reason == ACP::Protocol::StopReason::Cancelled
  puts "Turn was cancelled"
end

# JSON round-trip
json = ACP::Protocol::ToolKind::Execute.to_json  # => "\"execute\""
ACP::Protocol::ToolKind.from_json(json)           # => ToolKind::Execute

Session Update Types

These are the session/update notification types sent from the agent via the sessionUpdate discriminator.

ACP Standard Types:

Non-Standard Types (backward compatibility):

Transport Options

ACP::StdioTransport

Low-level transport over any IO pair:

transport = ACP::StdioTransport.new(
  reader: io_to_read_from,   # Agent's stdout
  writer: io_to_write_to,    # Agent's stdin
  buffer_size: 256            # Channel buffer (default: 256)
)

ACP::ProcessTransport

Spawns a child process and wires up stdio:

transport = ACP::ProcessTransport.new(
  "claude-code",
  args: ["--stdio"],
  env: {"API_KEY" => "..."},
  chdir: "/my/project",
  stderr: STDERR,              # Where to send agent's stderr
  buffer_size: 256
)

# Additional methods:
transport.process       # => Process
transport.terminated?   # => Bool
transport.wait          # => Process::Status

ACP.connect (Convenience)

client = ACP.connect(
  "my-agent",
  args: ["--stdio"],
  client_name: "my-editor",
  client_version: "1.0",
  capabilities: ACP::Protocol::ClientCapabilities.new,
  env: nil,
  chdir: nil
)

Error Types

Error Code Constants (ACP::Protocol::ErrorCode):

Interactive Client Example

An interactive CLI client is included in examples/interactive_client.cr:

# Build and run
crystal run examples/interactive_client.cr -- my-agent --stdio

# With environment variables
ACP_LOG_LEVEL=debug ACP_CWD=/my/project ACP_TIMEOUT=60 \
  crystal run examples/interactive_client.cr -- my-agent --stdio

Interactive Commands

Environment Variables

Protocol Flow

Client                              Agent
  │                                    │
  │──── initialize ───────────────────▶│
  │◀─── initialize result ────────────│
  │                                    │
  │──── authenticate (optional) ──────▶│
  │◀─── authenticate result ──────────│
  │                                    │
  │──── session/new ──────────────────▶│
  │◀─── session/new result ───────────│
  │                                    │
  │──── session/prompt ───────────────▶│
  │                                    │
  │◀─── session/update (chunk) ───────│  ┐
  │◀─── session/update (chunk) ───────│  │ Streaming
  │◀─── session/update (tool_call) ───│  │ updates
  │                                    │  │
  │◀─── session/request_permission ───│  │ Agent asks
  │──── permission response ──────────▶│  │ for permission
  │                                    │  │
  │◀─── session/update (tool_update) ─│  │
  │◀─── session/update (chunk) ───────│  ┘
  │◀─── session/prompt result ────────│
  │                                    │
  │──── session/set_mode ─────────────▶│  (optional)
  │◀─── session/set_mode result ──────│
  │                                    │
  │──── session/set_config_option ────▶│  (optional)
  │◀─── session/set_config_option res ─│
  │                                    │
  │──── session/cancel ───────────────▶│  (notification, no response)
  │                                    │

ACP Spec Compliance

This library implements the Agent Client Protocol v1 as a client-side library. Below is a summary of what is supported:

Agent Methods (Client → Agent)

Client Methods (Agent → Client)

Session Update Notifications

Protocol Types

Development

# Run specs
crystal spec

# Run specs with verbose output
crystal spec --verbose

# Format code
crystal tool format

# Build the interactive example
crystal build examples/interactive_client.cr -o bin/acp-client

Project Structure

src/acp/
├── acp.cr                       # Main entry point and ACP.connect convenience
├── client.cr                    # Core client with typed handler dispatch
├── errors.cr                    # Error types with ACP-specific codes
├── session.cr                   # High-level session wrapper and PromptBuilder
├── transport.cr                 # Stdio/Process transports
├── version.cr                   # Version constants
└── protocol/
    ├── capabilities.cr          # Client/Agent capabilities, MCP server configs
    ├── client_methods.cr        # fs/*, terminal/* request/response types
    ├── content_block.cr         # ContentBlock discriminated union
    ├── enums.cr                 # StopReason, ToolKind, ToolCallStatus, etc.
    ├── tool_call_content.cr     # ToolCallContent, Diff, Terminal, Location
    ├── types.cr                 # All method params/results, JSON-RPC builders
    └── updates.cr               # SessionUpdate discriminated union

src/
├── acp.cr                          # Main entry point
└── acp/
    ├── version.cr                  # Version and protocol version constants
    ├── errors.cr                   # Custom error types
    ├── transport.cr                # Transport layer (Stdio, Process)
    ├── client.cr                   # Core ACP client
    ├── session.cr                  # High-level session wrapper + PromptBuilder
    └── protocol/
        ├── types.cr                # JSON-RPC messages, method params/results
        ├── capabilities.cr         # Client/Agent capability types, MCP server types
        ├── content_block.cr        # Content block types (text, image, audio, resource, resource_link)
        └── updates.cr              # Session update types (standard + backward-compat)
examples/
├── simple_client.cr                # Minimal example
├── content_blocks.cr               # Rich prompts with multiple content types
├── gemini_agent.cr                 # Gemini CLI as ACP agent
└── interactive_client.cr           # Interactive CLI client
spec/
├── spec_helper.cr
└── acp_spec.cr                     # Comprehensive test suite

Contributing

1. Fork it (https://github.com/hahwul/acp/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• hahwul - creator and maintainer

License

This project is licensed under the MIT License - see the LICENSE file for details.