https://github.com/hahwul/acp.cr
An unofficial Crystal implementation of the Agent Client Protocol (ACP)
https://github.com/hahwul/acp.cr
acp agent-client-protocol crystal
Last synced: about 2 months ago
JSON representation
An unofficial Crystal implementation of the Agent Client Protocol (ACP)
- Host: GitHub
- URL: https://github.com/hahwul/acp.cr
- Owner: hahwul
- License: mit
- Created: 2026-02-09T08:13:01.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-03-31T15:14:01.000Z (2 months ago)
- Last Synced: 2026-04-15T08:02:07.781Z (about 2 months ago)
- Topics: acp, agent-client-protocol, crystal
- Language: Crystal
- Homepage: https://acp.cr.hahwul.com
- Size: 237 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# ACP ā Agent Client Protocol for Crystal
An unofficial Crystal implementation of the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), which defines a JSON-RPC 2.0 based communication standard between code editors (clients) and AI coding agents.
š **Full documentation is available at [acp.cr.hahwul.com](https://acp.cr.hahwul.com/)**
## Installation
Add the dependency to your `shard.yml`:
```yaml
dependencies:
acp:
github: hahwul/acp
```
Then run:
```sh
shards install
```
## Quick Start
```crystal
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:
- `simple_client.cr` ā Basic connection and prompting
- `content_blocks.cr` ā Rich prompts with multiple content types
- `claude_code_agent.cr` ā Claude Code as an ACP agent
- `gemini_agent.cr` ā Gemini CLI as an ACP agent
- `codex_agent.cr` ā Codex via ACP adapter
- `interactive_client.cr` ā Full-featured interactive CLI client
```sh
crystal run examples/claude_code_agent.cr
crystal run examples/gemini_agent.cr
crystal run examples/interactive_client.cr -- my-agent --stdio
```
## Development
```sh
crystal spec
crystal tool format
```
## Contributing
1. Fork it ()
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](https://github.com/hahwul) - creator and maintainer
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.