claude-code-acp-rs: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code ACP Agent implemented in Rust. Enables editors like Zed to use Claude Code capabilities via the ACP (Agent Client Protocol).

Build & Development Commands

# Build and run (release)
cargo build --release && cargo run --release

# Run tests
cargo test --all-features --workspace

# Run a single test
cargo test <test_name> --all-features

# Lint with Clippy
cargo clippy --all-targets --all-features --workspace

# Format check
cargo fmt --all -- --check

# Format code
cargo fmt --all

Architecture

Core Modules

• agent/ - ACP protocol handler and session management

  • core.rs - ClaudeAcpAgent main struct
  • handlers.rs - ACP request handlers (initialize, session/new, session/prompt)
  • runner.rs - Entry point (run_acp())

• mcp/ - Tool system (MCP pattern)

  • acp_server.rs - ACP-integrated MCP server with notification support
  • registry.rs - Tool registration and discovery
  • tools/ - 22 built-in tools (bash, read, write, edit, grep, glob, etc.)
  • external.rs - External MCP server connections (framework for extensions)

• session/ - Session lifecycle management

  • manager.rs - Concurrent session storage (uses DashMap)
  • permission_manager.rs - Tool permission decisions
  • background_processes.rs - Child process management (avoids zombies)
  • usage.rs - Token usage tracking

• settings/ - Configuration system

  • manager.rs - Settings loading from ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json
  • permission_checker.rs - Permission rule evaluation
  • rule.rs - Permission rule parsing (regex/glob patterns)
  • watcher.rs - File change watching for dynamic reload

• converter/ - Protocol translation

  • prompt.rs - ACP requests → Claude SDK format
  • notification.rs - Claude SDK events → ACP notifications