claude-code-acp 0.1.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

claude_code_acp/__init__.py

@@ -8,10 +8,20 @@ allowing Claude Code to work with any ACP-compatible client like Zed, Neovim, et
 import asyncio
 
 from .agent import ClaudeAcpAgent
-
-__version__ = "0.1.0"
-
-__all__ = ["ClaudeAcpAgent", "main", "run"]
+from .client import ClaudeClient, ClaudeEvents
+from .acp_client import AcpClient, AcpClientEvents
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "ClaudeAcpAgent",
+    "ClaudeClient",
+    "ClaudeEvents",
+    "AcpClient",
+    "AcpClientEvents",
+    "main",
+    "run",
+]
 
 
 async def run() -> None:

claude_code_acp/acp_client.py

@@ -0,0 +1,374 @@
+"""
+ACP Client - Connect to any ACP-compatible agent.
+
+This module provides a client that can connect to any ACP agent
+(like claude-code-acp, or Zed's TypeScript version) via subprocess.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass
+from typing import Any, Callable, Coroutine
+
+from acp.client.connection import ClientSideConnection
+from acp.schema import (
+    AgentMessageChunk,
+    AgentThoughtChunk,
+    Implementation,
+    PermissionOption,
+    RequestPermissionResponse,
+    TextContentBlock,
+    ToolCallProgress,
+    ToolCallStart,
+    ToolCallUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["AcpClient", "AcpClientEvents"]
+
+
+@dataclass
+class AcpClientEvents:
+    """Event handlers for ACP client."""
+
+    on_text: Callable[[str], Coroutine[Any, Any, None]] | None = None
+    on_thinking: Callable[[str], Coroutine[Any, Any, None]] | None = None
+    on_tool_start: Callable[[str, str, dict], Coroutine[Any, Any, None]] | None = None
+    on_tool_end: Callable[[str, str, Any], Coroutine[Any, Any, None]] | None = None
+    on_permission: Callable[[str, dict, list], Coroutine[Any, Any, str]] | None = None
+    on_error: Callable[[Exception], Coroutine[Any, Any, None]] | None = None
+    on_complete: Callable[[], Coroutine[Any, Any, None]] | None = None
+
+
+class AcpClient:
+    """
+    ACP Client that connects to any ACP-compatible agent.
+
+    This client spawns an ACP agent as a subprocess and communicates
+    via the Agent Client Protocol (JSON-RPC over stdio).
+
+    Example:
+        ```python
+        # Connect to claude-code-acp
+        client = AcpClient(command="claude-code-acp")
+
+        # Or connect to the TypeScript version
+        client = AcpClient(command="npx", args=["@anthropic/claude-code-acp"])
+
+        @client.on_text
+        async def handle_text(text):
+            print(text, end="")
+
+        async with client:
+            await client.prompt("Hello!")
+        ```
+    """
+
+    def __init__(
+        self,
+        command: str = "claude-code-acp",
+        args: list[str] | None = None,
+        cwd: str = ".",
+        env: dict[str, str] | None = None,
+    ):
+        """
+        Initialize the ACP client.
+
+        Args:
+            command: The ACP agent command to run.
+            args: Additional arguments for the command.
+            cwd: Working directory for the agent.
+            env: Additional environment variables.
+        """
+        self.command = command
+        self.args = args or []
+        self.cwd = cwd
+        self.env = env
+        self.events = AcpClientEvents()
+
+        self._process: asyncio.subprocess.Process | None = None
+        self._connection: ClientSideConnection | None = None
+        self._session_id: str | None = None
+        self._text_buffer = ""
+        self._initialized = False
+
+    # --- Event decorators ---
+
+    def on_text(self, func: Callable[[str], Coroutine[Any, Any, None]]):
+        """Register handler for text responses."""
+        self.events.on_text = func
+        return func
+
+    def on_thinking(self, func: Callable[[str], Coroutine[Any, Any, None]]):
+        """Register handler for thinking blocks."""
+        self.events.on_thinking = func
+        return func
+
+    def on_tool_start(self, func: Callable[[str, str, dict], Coroutine[Any, Any, None]]):
+        """Register handler for tool start events."""
+        self.events.on_tool_start = func
+        return func
+
+    def on_tool_end(self, func: Callable[[str, str, Any], Coroutine[Any, Any, None]]):
+        """Register handler for tool end events."""
+        self.events.on_tool_end = func
+        return func
+
+    def on_permission(self, func: Callable[[str, dict, list], Coroutine[Any, Any, str]]):
+        """
+        Register handler for permission requests.
+
+        The handler receives (name, input, options) and should return
+        the option_id to select (e.g., "allow", "reject", "allow_always").
+        """
+        self.events.on_permission = func
+        return func
+
+    def on_error(self, func: Callable[[Exception], Coroutine[Any, Any, None]]):
+        """Register handler for errors."""
+        self.events.on_error = func
+        return func
+
+    def on_complete(self, func: Callable[[], Coroutine[Any, Any, None]]):
+        """Register handler for completion."""
+        self.events.on_complete = func
+        return func
+
+    # --- Connection management ---
+
+    async def connect(self) -> None:
+        """Connect to the ACP agent."""
+        if self._process is not None:
+            return
+
+        # Spawn the agent process
+        self._process = await asyncio.create_subprocess_exec(
+            self.command,
+            *self.args,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=self.cwd,
+            env=self.env,
+        )
+
+        if self._process.stdin is None or self._process.stdout is None:
+            raise RuntimeError("Failed to create subprocess pipes")
+
+        # Create ACP connection
+        # Note: ClientSideConnection expects (writer, reader) - stdin is writer, stdout is reader
+        self._connection = ClientSideConnection(
+            to_client=self._create_client_handler(),
+            input_stream=self._process.stdin,
+            output_stream=self._process.stdout,
+        )
+
+        # Initialize the connection
+        init_response = await self._connection.initialize(
+            protocol_version=1,
+            client_info=Implementation(
+                name="claude-code-acp-client",
+                version="0.2.0",
+            ),
+        )
+        logger.info(f"Connected to agent: {init_response.agent_info}")
+        self._initialized = True
+
+    async def disconnect(self) -> None:
+        """Disconnect from the ACP agent."""
+        if self._connection:
+            await self._connection.close()
+            self._connection = None
+
+        if self._process:
+            self._process.terminate()
+            await self._process.wait()
+            self._process = None
+
+        self._initialized = False
+        self._session_id = None
+
+    async def __aenter__(self) -> "AcpClient":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.disconnect()
+
+    # --- Session management ---
+
+    async def new_session(self) -> str:
+        """Create a new session."""
+        if not self._connection:
+            raise RuntimeError("Not connected")
+
+        response = await self._connection.new_session(
+            cwd=self.cwd,
+            mcp_servers=[],
+        )
+        self._session_id = response.session_id
+        return self._session_id
+
+    async def prompt(self, text: str) -> str:
+        """
+        Send a prompt and receive the response.
+
+        Events will be dispatched to registered handlers as they arrive.
+
+        Args:
+            text: The prompt text to send.
+
+        Returns:
+            The full text response.
+        """
+        if not self._connection:
+            raise RuntimeError("Not connected")
+
+        if not self._session_id:
+            await self.new_session()
+
+        self._text_buffer = ""
+
+        try:
+            response = await self._connection.prompt(
+                prompt=[TextContentBlock(type="text", text=text)],
+                session_id=self._session_id,
+            )
+
+            if self.events.on_complete:
+                await self.events.on_complete()
+
+            return self._text_buffer
+
+        except Exception as e:
+            if self.events.on_error:
+                await self.events.on_error(e)
+            raise
+
+    async def cancel(self) -> None:
+        """Cancel the current operation."""
+        if self._connection and self._session_id:
+            await self._connection.cancel(session_id=self._session_id)
+
+    async def set_mode(self, mode: str) -> None:
+        """Set the permission mode."""
+        if not self._connection or not self._session_id:
+            raise RuntimeError("No active session")
+
+        await self._connection.set_session_mode(
+            mode_id=mode,
+            session_id=self._session_id,
+        )
+
+    # --- Internal handlers ---
+
+    def _create_client_handler(self):
+        """Create the client handler for receiving agent messages."""
+        client = self
+
+        class ClientHandler:
+            """Handles incoming messages from the agent."""
+
+            async def session_update(self, session_id: str, update: Any) -> None:
+                """Handle session updates from the agent."""
+                update_type = type(update).__name__
+
+                if isinstance(update, AgentMessageChunk):
+                    content = getattr(update, "content", None)
+                    if content and hasattr(content, "text"):
+                        text = content.text
+                        if text and text not in client._text_buffer:
+                            client._text_buffer += text
+                            if client.events.on_text:
+                                await client.events.on_text(text)
+
+                elif isinstance(update, AgentThoughtChunk):
+                    content = getattr(update, "content", None)
+                    if content and hasattr(content, "text"):
+                        if client.events.on_thinking:
+                            await client.events.on_thinking(content.text)
+
+                elif isinstance(update, ToolCallStart):
+                    if client.events.on_tool_start:
+                        await client.events.on_tool_start(
+                            update.tool_call_id,
+                            update.title or "",
+                            update.raw_input or {},
+                        )
+
+                elif isinstance(update, ToolCallProgress):
+                    if client.events.on_tool_end:
+                        await client.events.on_tool_end(
+                            update.tool_call_id,
+                            update.status or "",
+                            update.raw_output,
+                        )
+
+            async def request_permission(
+                self,
+                options: list[PermissionOption],
+                session_id: str,
+                tool_call: ToolCallUpdate,
+                **kwargs: Any,
+            ) -> RequestPermissionResponse:
+                """Handle permission requests from the agent."""
+                name = tool_call.title or "Unknown"
+                raw_input = tool_call.raw_input or {}
+                option_list = [{"id": o.option_id, "name": o.name} for o in options]
+
+                # Default to allow
+                selected_id = "allow"
+
+                if client.events.on_permission:
+                    selected_id = await client.events.on_permission(
+                        name, raw_input, option_list
+                    )
+
+                return RequestPermissionResponse(
+                    outcome={"outcome": "selected", "option_id": selected_id}
+                )
+
+            async def write_text_file(self, **kwargs) -> None:
+                """Handle write file requests (stub)."""
+                pass
+
+            async def read_text_file(self, **kwargs) -> dict:
+                """Handle read file requests (stub)."""
+                return {"content": ""}
+
+            async def create_terminal(self, **kwargs) -> dict:
+                """Handle terminal creation (stub)."""
+                return {"terminal_id": "stub"}
+
+            async def terminal_output(self, **kwargs) -> dict:
+                """Handle terminal output requests (stub)."""
+                return {"output": ""}
+
+            async def release_terminal(self, **kwargs) -> None:
+                """Handle terminal release (stub)."""
+                pass
+
+            async def wait_for_terminal_exit(self, **kwargs) -> dict:
+                """Handle terminal exit wait (stub)."""
+                return {"exit_code": 0}
+
+            async def kill_terminal(self, **kwargs) -> None:
+                """Handle terminal kill (stub)."""
+                pass
+
+            async def ext_method(self, method: str, params: dict) -> dict:
+                """Handle extension methods."""
+                return {}
+
+            async def ext_notification(self, method: str, params: dict) -> None:
+                """Handle extension notifications."""
+                pass
+
+            def on_connect(self, conn: Any) -> None:
+                """Called when connected."""
+                pass
+
+        return ClientHandler()

claude_code_acp/client.py

@@ -0,0 +1,317 @@
+"""
+Event-driven Claude client wrapper.
+
+Provides a simple, decorator-based API for interacting with Claude.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Callable, Coroutine
+
+from .agent import ClaudeAcpAgent
+
+
+@dataclass
+class ClaudeEvents:
+    """Event handlers for Claude responses."""
+
+    on_text: Callable[[str], Coroutine[Any, Any, None]] | None = None
+    on_thinking: Callable[[str], Coroutine[Any, Any, None]] | None = None
+    on_tool_start: Callable[[str, str, dict], Coroutine[Any, Any, None]] | None = None
+    on_tool_end: Callable[[str, str, Any], Coroutine[Any, Any, None]] | None = None
+    on_permission: Callable[[str, dict], Coroutine[Any, Any, bool]] | None = None
+    on_error: Callable[[Exception], Coroutine[Any, Any, None]] | None = None
+    on_complete: Callable[[], Coroutine[Any, Any, None]] | None = None
+
+
+class ClaudeClient:
+    """
+    Event-driven Claude client using ACP.
+
+    Example:
+        ```python
+        client = ClaudeClient(cwd="/path/to/project")
+
+        @client.on_text
+        async def handle_text(text):
+            print(text, end="", flush=True)
+
+        @client.on_tool_start
+        async def handle_tool(tool_id, name, input):
+            print(f"Running: {name}")
+
+        @client.on_permission
+        async def handle_permission(name, input):
+            return True  # or prompt user
+
+        response = await client.query("What files are in this directory?")
+        ```
+    """
+
+    def __init__(self, cwd: str = "."):
+        """
+        Initialize the Claude client.
+
+        Args:
+            cwd: Working directory for Claude operations.
+        """
+        self.cwd = cwd
+        self.agent = ClaudeAcpAgent()
+        self.session_id: str | None = None
+        self.events = ClaudeEvents()
+        self._text_buffer = ""
+        self._seen_text = set()  # Track seen text to avoid duplicates
+
+    # --- Decorator-based event registration ---
+
+    def on_text(self, func: Callable[[str], Coroutine[Any, Any, None]]):
+        """
+        Register handler for text responses.
+
+        The handler receives streaming text chunks as they arrive.
+
+        Example:
+            @client.on_text
+            async def handle_text(text: str):
+                print(text, end="", flush=True)
+        """
+        self.events.on_text = func
+        return func
+
+    def on_thinking(self, func: Callable[[str], Coroutine[Any, Any, None]]):
+        """
+        Register handler for thinking/reasoning blocks.
+
+        Example:
+            @client.on_thinking
+            async def handle_thinking(text: str):
+                print(f"[Thinking: {text}]")
+        """
+        self.events.on_thinking = func
+        return func
+
+    def on_tool_start(
+        self, func: Callable[[str, str, dict], Coroutine[Any, Any, None]]
+    ):
+        """
+        Register handler for tool call start events.
+
+        Args to handler:
+            tool_id: Unique identifier for the tool call
+            name: Human-readable tool name/title
+            input: Tool input parameters
+
+        Example:
+            @client.on_tool_start
+            async def handle_tool_start(tool_id: str, name: str, input: dict):
+                print(f"🔧 Starting: {name}")
+        """
+        self.events.on_tool_start = func
+        return func
+
+    def on_tool_end(self, func: Callable[[str, str, Any], Coroutine[Any, Any, None]]):
+        """
+        Register handler for tool completion events.
+
+        Args to handler:
+            tool_id: Unique identifier for the tool call
+            status: "completed" or "failed"
+            output: Tool output/result
+
+        Example:
+            @client.on_tool_end
+            async def handle_tool_end(tool_id: str, status: str, output: Any):
+                icon = "✅" if status == "completed" else "❌"
+                print(f" {icon}")
+        """
+        self.events.on_tool_end = func
+        return func
+
+    def on_permission(
+        self, func: Callable[[str, dict], Coroutine[Any, Any, bool]]
+    ):
+        """
+        Register handler for permission requests.
+
+        The handler should return True to allow, False to deny.
+
+        Example:
+            @client.on_permission
+            async def handle_permission(name: str, input: dict) -> bool:
+                response = input("Allow {name}? [y/N]: ")
+                return response.lower() == "y"
+        """
+        self.events.on_permission = func
+        return func
+
+    def on_error(self, func: Callable[[Exception], Coroutine[Any, Any, None]]):
+        """
+        Register handler for errors.
+
+        Example:
+            @client.on_error
+            async def handle_error(e: Exception):
+                print(f"Error: {e}")
+        """
+        self.events.on_error = func
+        return func
+
+    def on_complete(self, func: Callable[[], Coroutine[Any, Any, None]]):
+        """
+        Register handler for query completion.
+
+        Example:
+            @client.on_complete
+            async def handle_complete():
+                print("\\n--- Done ---")
+        """
+        self.events.on_complete = func
+        return func
+
+    # --- Main API ---
+
+    async def start_session(self) -> str:
+        """
+        Start a new Claude session.
+
+        Returns:
+            The session ID.
+        """
+        session = await self.agent.new_session(cwd=self.cwd, mcp_servers=[])
+        self.session_id = session.session_id
+        return self.session_id
+
+    async def query(self, prompt: str) -> str:
+        """
+        Send a query and receive events via registered handlers.
+
+        Args:
+            prompt: The message to send to Claude.
+
+        Returns:
+            The full text response as a string.
+
+        Example:
+            response = await client.query("Explain this code")
+            print(f"Full response: {response}")
+        """
+        if not self.session_id:
+            await self.start_session()
+
+        self._text_buffer = ""
+        self._seen_text = set()
+
+        # Wire up the event handler
+        self.agent._conn = self._create_event_handler()
+
+        try:
+            await self.agent.prompt(
+                prompt=[{"type": "text", "text": prompt}],
+                session_id=self.session_id,
+            )
+
+            if self.events.on_complete:
+                await self.events.on_complete()
+
+        except Exception as e:
+            if self.events.on_error:
+                await self.events.on_error(e)
+            raise
+
+        return self._text_buffer
+
+    async def set_mode(self, mode: str) -> None:
+        """
+        Set the permission mode for the session.
+
+        Args:
+            mode: One of "default", "acceptEdits", "plan", "bypassPermissions"
+        """
+        if not self.session_id:
+            await self.start_session()
+
+        await self.agent.set_session_mode(mode_id=mode, session_id=self.session_id)
+
+    def _create_event_handler(self):
+        """Create the internal event handler that bridges to user callbacks."""
+        client = self
+
+        class EventHandler:
+            async def session_update(self, session_id: str, update: Any) -> None:
+                update_type = type(update).__name__
+
+                if "AgentMessageChunk" in update_type:
+                    content = getattr(update, "content", None)
+                    if content and hasattr(content, "text"):
+                        text = content.text
+                        if not text:
+                            return
+
+                        # Smart deduplication for streaming:
+                        # - If buffer is empty, this is new text
+                        # - If text is already in buffer, skip (duplicate)
+                        # - If text extends buffer, only emit the new part
+                        current_len = len(client._text_buffer)
+
+                        if current_len == 0:
+                            # First chunk
+                            client._text_buffer = text
+                            if client.events.on_text:
+                                await client.events.on_text(text)
+                        elif text in client._text_buffer:
+                            # Exact duplicate, skip
+                            pass
+                        elif client._text_buffer in text:
+                            # Text extends buffer - emit only new part
+                            new_part = text[current_len:]
+                            if new_part:
+                                client._text_buffer = text
+                                if client.events.on_text:
+                                    await client.events.on_text(new_part)
+                        else:
+                            # Completely new text chunk
+                            client._text_buffer += text
+                            if client.events.on_text:
+                                await client.events.on_text(text)
+
+                elif "AgentThoughtChunk" in update_type:
+                    content = getattr(update, "content", None)
+                    if content and hasattr(content, "text"):
+                        if client.events.on_thinking:
+                            await client.events.on_thinking(content.text)
+
+                elif "ToolCallStart" in update_type:
+                    if client.events.on_tool_start:
+                        await client.events.on_tool_start(
+                            getattr(update, "tool_call_id", ""),
+                            getattr(update, "title", ""),
+                            getattr(update, "raw_input", {}),
+                        )
+
+                elif "ToolCallProgress" in update_type:
+                    if client.events.on_tool_end:
+                        await client.events.on_tool_end(
+                            getattr(update, "tool_call_id", ""),
+                            getattr(update, "status", ""),
+                            getattr(update, "raw_output", None),
+                        )
+
+            async def request_permission(self, **kwargs: Any) -> dict:
+                tool_call = kwargs.get("tool_call", {})
+                name = tool_call.get("title", "Unknown")
+                raw_input = tool_call.get("raw_input", {})
+
+                approved = True
+                if client.events.on_permission:
+                    approved = await client.events.on_permission(name, raw_input)
+
+                if approved:
+                    return {"outcome": {"outcome": "selected", "option_id": "allow"}}
+                return {"outcome": {"outcome": "selected", "option_id": "reject"}}
+
+        return EventHandler()
+
+
+__all__ = ["ClaudeClient", "ClaudeEvents"]

claude_code_acp-0.3.0.dist-info/METADATA

@@ -0,0 +1,418 @@
+Metadata-Version: 2.4
+Name: claude-code-acp
+Version: 0.3.0
+Summary: ACP-compatible agent for Claude Code (Python version)
+Project-URL: Homepage, https://github.com/yazelin/claude-code-acp-py
+Project-URL: Repository, https://github.com/yazelin/claude-code-acp-py
+Project-URL: Issues, https://github.com/yazelin/claude-code-acp-py/issues
+Author: yazelin
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acp,agent,anthropic,claude,claude-code,python
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Requires-Dist: agent-client-protocol>=0.7.0
+Requires-Dist: claude-agent-sdk>=0.1.29
+Description-Content-Type: text/markdown
+
+# Claude Code ACP (Python)
+
+[![PyPI](https://img.shields.io/pypi/v/claude-code-acp)](https://pypi.org/project/claude-code-acp/)
+[![Python](https://img.shields.io/pypi/pyversions/claude-code-acp)](https://pypi.org/project/claude-code-acp/)
+[![License](https://img.shields.io/github/license/yazelin/claude-code-acp-py)](https://github.com/yazelin/claude-code-acp-py/blob/main/LICENSE)
+
+**Python implementation of ACP (Agent Client Protocol) for Claude Code.**
+
+This package bridges the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) with the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), providing two ways to use Claude:
+
+1. **ACP Server** - Connect Claude to any ACP-compatible editor (Zed, Neovim, JetBrains, etc.)
+2. **Python Client** - Event-driven API for building Python applications with Claude
+
+## Features
+
+- **Uses Claude CLI subscription** - No API key needed, uses your existing Claude subscription
+- **Full ACP protocol support** - Compatible with Zed, Neovim, and other ACP clients
+- **Bidirectional communication** - Permission requests, tool calls, streaming responses
+- **Event-driven Python API** - Decorator-based handlers for easy integration
+- **Session management** - Create, fork, resume, list sessions
+- **Multiple permission modes** - default, acceptEdits, plan, bypassPermissions
+
+## Installation
+
+```bash
+pip install claude-code-acp
+```
+
+Or with uv:
+
+```bash
+uv tool install claude-code-acp
+```
+
+## Requirements
+
+- Python 3.10+
+- Claude CLI installed and authenticated (`claude /login`)
+
+---
+
+## Components
+
+| Class | Type | Description |
+|-------|------|-------------|
+| `ClaudeAcpAgent` | ACP Server | For editors (Zed, Neovim) to connect |
+| `ClaudeClient` | Python API | Event-driven wrapper (uses agent internally) |
+| `AcpClient` | ACP Client | Connect to any ACP agent via subprocess |
+
+---
+
+## Usage 1: ACP Server for Editors
+
+Run as an ACP server to connect Claude to your editor:
+
+```bash
+claude-code-acp
+```
+
+### Zed Editor
+
+Add to your Zed `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Claude Code Python": {
+      "type": "custom",
+      "command": "claude-code-acp",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+Then open the Agent Panel (`Ctrl+?` / `Cmd+?`) and select "Claude Code Python" from the `+` menu.
+
+### Other Editors
+
+Any [ACP-compatible client](https://agentclientprotocol.com/overview/clients) can connect by spawning `claude-code-acp` as a subprocess and communicating via stdio.
+
+---
+
+## Usage 2: Python Event-Driven API
+
+Use `ClaudeClient` for building Python applications with Claude:
+
+```python
+import asyncio
+from claude_code_acp import ClaudeClient
+
+async def main():
+    client = ClaudeClient(cwd=".")
+
+    @client.on_text
+    async def handle_text(text: str):
+        """Called for each text chunk from Claude."""
+        print(text, end="", flush=True)
+
+    @client.on_tool_start
+    async def handle_tool_start(tool_id: str, name: str, input: dict):
+        """Called when Claude starts using a tool."""
+        print(f"\n🔧 {name}")
+
+    @client.on_tool_end
+    async def handle_tool_end(tool_id: str, status: str, output):
+        """Called when a tool completes."""
+        icon = "✅" if status == "completed" else "❌"
+        print(f" {icon}")
+
+    @client.on_permission
+    async def handle_permission(name: str, input: dict) -> bool:
+        """Called when Claude needs permission. Return True to allow."""
+        print(f"🔐 Permission requested: {name}")
+        return True  # or prompt user
+
+    @client.on_complete
+    async def handle_complete():
+        """Called when the query completes."""
+        print("\n--- Done ---")
+
+    # Send a query
+    response = await client.query("Create a hello.py file that prints Hello World")
+    print(f"\nFull response: {response}")
+
+asyncio.run(main())
+```
+
+### Event Handlers
+
+| Decorator | Arguments | Description |
+|-----------|-----------|-------------|
+| `@client.on_text` | `(text: str)` | Streaming text chunks from Claude |
+| `@client.on_thinking` | `(text: str)` | Thinking/reasoning blocks |
+| `@client.on_tool_start` | `(tool_id, name, input)` | Tool execution started |
+| `@client.on_tool_end` | `(tool_id, status, output)` | Tool execution completed |
+| `@client.on_permission` | `(name, input) -> bool` | Permission request (return True/False) |
+| `@client.on_error` | `(exception)` | Error occurred |
+| `@client.on_complete` | `()` | Query completed |
+
+### Client Methods
+
+```python
+# Start a new session
+session_id = await client.start_session()
+
+# Send a query (returns full response text)
+response = await client.query("Your prompt here")
+
+# Set permission mode
+await client.set_mode("acceptEdits")  # or "default", "plan", "bypassPermissions"
+```
+
+---
+
+## Usage 3: ACP Client (Connect to Any Agent)
+
+Use `AcpClient` to connect to any ACP-compatible agent:
+
+```python
+import asyncio
+from claude_code_acp import AcpClient
+
+async def main():
+    # Connect to claude-code-acp (Python version)
+    client = AcpClient(command="claude-code-acp")
+
+    # Or connect to the TypeScript version
+    # client = AcpClient(command="npx", args=["@zed-industries/claude-code-acp"])
+
+    # Or any other ACP agent
+    # client = AcpClient(command="my-custom-agent")
+
+    @client.on_text
+    async def handle_text(text: str):
+        print(text, end="", flush=True)
+
+    @client.on_tool_start
+    async def handle_tool(tool_id: str, name: str, input: dict):
+        print(f"\n🔧 {name}")
+
+    @client.on_permission
+    async def handle_permission(name: str, input: dict, options: list) -> str:
+        """Return option_id: 'allow', 'reject', or 'allow_always'"""
+        print(f"🔐 Permission: {name}")
+        return "allow"
+
+    @client.on_complete
+    async def handle_complete():
+        print("\n--- Done ---")
+
+    async with client:
+        response = await client.prompt("What files are here?")
+
+asyncio.run(main())
+```
+
+### AcpClient vs ClaudeClient
+
+| Feature | `ClaudeClient` | `AcpClient` |
+|---------|---------------|-------------|
+| Uses | Claude Agent SDK directly | Any ACP agent via subprocess |
+| Connection | In-process | Subprocess + stdio |
+| Agents | Claude only | Any ACP-compatible agent |
+| Use case | Simple Python apps | Multi-agent, testing, flexibility |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              Your Application                                │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                             │
+│  ┌─────────────────┐                      ┌─────────────────────────────┐  │
+│  │   Zed/Neovim    │                      │     Python Application      │  │
+│  │   (ACP Client)  │                      │                             │  │
+│  └────────┬────────┘                      │  client = ClaudeClient()    │  │
+│           │                               │                             │  │
+│           │ ACP Protocol                  │  @client.on_text            │  │
+│           │ (stdio/JSON-RPC)              │  async def handle(text):    │  │
+│           │                               │      print(text)            │  │
+│           ▼                               │                             │  │
+│  ┌────────────────────────────────────────┴─────────────────────────────┐  │
+│  │                                                                       │  │
+│  │                      claude-code-acp (This Package)                   │  │
+│  │                                                                       │  │
+│  │   ┌─────────────────────┐      ┌─────────────────────────────────┐   │  │
+│  │   │   ClaudeAcpAgent    │      │        ClaudeClient             │   │  │
+│  │   │   (ACP Server)      │      │    (Event-driven wrapper)       │   │  │
+│  │   └──────────┬──────────┘      └───────────────┬─────────────────┘   │  │
+│  │              │                                 │                      │  │
+│  │              └────────────────┬────────────────┘                      │  │
+│  │                               │                                       │  │
+│  └───────────────────────────────┼───────────────────────────────────────┘  │
+│                                  │                                          │
+│                                  ▼                                          │
+│                    ┌─────────────────────────────┐                          │
+│                    │    Claude Agent SDK         │                          │
+│                    │    (claude-agent-sdk)       │                          │
+│                    └──────────────┬──────────────┘                          │
+│                                   │                                         │
+│                                   ▼                                         │
+│                    ┌─────────────────────────────┐                          │
+│                    │       Claude CLI            │                          │
+│                    │  (Your Claude Subscription) │                          │
+│                    └─────────────────────────────┘                          │
+│                                                                             │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## What We Built
+
+This project combines two official SDKs to create a complete Python solution:
+
+### Integrated Components
+
+| Component | Source | Purpose |
+|-----------|--------|---------|
+| [Agent Client Protocol SDK](https://github.com/anthropics/agent-client-protocol) | Anthropic | ACP server/client protocol implementation |
+| [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) | Anthropic | Claude CLI wrapper with streaming support |
+
+### Our Contributions
+
+1. **ClaudeAcpAgent** (`agent.py`)
+   - Bridges Claude Agent SDK with ACP protocol
+   - Converts Claude messages to ACP session updates
+   - Handles bidirectional permission requests
+   - Session management (create, fork, resume, list)
+
+2. **ClaudeClient** (`client.py`)
+   - Event-driven Python API with decorators
+   - Smart text deduplication for streaming
+   - Simple permission handling
+   - Clean async/await interface
+
+3. **ACP Server Entry Point**
+   - Standalone `claude-code-acp` command
+   - Direct integration with Zed and other ACP clients
+   - No configuration needed
+
+### Why This Package?
+
+| Approach | API Key | Subscription | ACP Support | Event-Driven |
+|----------|---------|--------------|-------------|--------------|
+| Anthropic API directly | ✅ Required | ❌ | ❌ | ❌ |
+| Claude Agent SDK | ❌ | ✅ Uses CLI | ❌ | Partial |
+| **claude-code-acp** | ❌ | ✅ Uses CLI | ✅ Full | ✅ Full |
+
+---
+
+## Examples
+
+### Simple Chat
+
+```python
+import asyncio
+from claude_code_acp import ClaudeClient
+
+async def main():
+    client = ClaudeClient()
+
+    @client.on_text
+    async def on_text(text):
+        print(text, end="")
+
+    while True:
+        user_input = input("\nYou: ")
+        if user_input.lower() == "quit":
+            break
+        await client.query(user_input)
+
+asyncio.run(main())
+```
+
+### File Operations with Permission Control
+
+```python
+import asyncio
+from claude_code_acp import ClaudeClient
+
+async def main():
+    client = ClaudeClient(cwd="/path/to/project")
+
+    @client.on_text
+    async def on_text(text):
+        print(text, end="")
+
+    @client.on_permission
+    async def on_permission(name, input):
+        response = input(f"Allow '{name}'? [y/N]: ")
+        return response.lower() == "y"
+
+    await client.query("Refactor the main.py file to use async/await")
+
+asyncio.run(main())
+```
+
+### Auto-approve Mode
+
+```python
+import asyncio
+from claude_code_acp import ClaudeClient
+
+async def main():
+    client = ClaudeClient(cwd=".")
+
+    # Bypass all permission checks
+    await client.set_mode("bypassPermissions")
+
+    @client.on_text
+    async def on_text(text):
+        print(text, end="")
+
+    await client.query("Create a complete Flask app with tests")
+
+asyncio.run(main())
+```
+
+---
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/yazelin/claude-code-acp-py
+cd claude-code-acp-py
+
+# Install dependencies
+uv sync
+
+# Run locally
+uv run claude-code-acp
+
+# Run tests
+uv run python -c "from claude_code_acp import ClaudeClient; print('OK')"
+```
+
+---
+
+## Related Projects
+
+- [claude-code-acp](https://github.com/zed-industries/claude-code-acp) - TypeScript version by Zed Industries
+- [agent-client-protocol](https://github.com/anthropics/agent-client-protocol) - ACP specification and SDKs
+- [claude-agent-sdk-python](https://github.com/anthropics/claude-agent-sdk-python) - Official Claude Agent SDK
+
+---
+
+## License
+
+MIT

claude_code_acp-0.3.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+claude_code_acp/__init__.py,sha256=sY6dO2pXQnnImk6ChOl7MF3HOrp6GBdIiLl5CseuaWs,828
+claude_code_acp/__main__.py,sha256=zuAdIOmaCsDeRxj2yIl_qMx-74QFaA3nWiS8gti0og0,118
+claude_code_acp/acp_client.py,sha256=E0e8XBco3cBV4sPi4txXpS13WPXRDodwYqHpXmCJd4A,12572
+claude_code_acp/agent.py,sha256=qos32gnMAilOlz6ebllkmuJZS3UgpbAtAZw58r3SYig,20619
+claude_code_acp/client.py,sha256=jKi6tPNqNu0GWTsXxVa1BREGE1wkm_kbIEDulXKGDHE,10680
+claude_code_acp-0.3.0.dist-info/METADATA,sha256=gGQDM94g6UpnPsIDPXkWQyZ6Ig2SanGxI3vvIbixRew,15477
+claude_code_acp-0.3.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+claude_code_acp-0.3.0.dist-info/entry_points.txt,sha256=cc_pkg_V_1zctD5CUqjATCxglkf5-UArEMfN3q9We-A,57
+claude_code_acp-0.3.0.dist-info/licenses/LICENSE,sha256=5NCM9Q9UTfsn-VyafO7htdlYyPPO8H-NHYrO5UV9sT4,1064
+claude_code_acp-0.3.0.dist-info/RECORD,,

claude_code_acp-0.1.0.dist-info/METADATA

@@ -1,111 +0,0 @@
-Metadata-Version: 2.4
-Name: claude-code-acp
-Version: 0.1.0
-Summary: ACP-compatible agent for Claude Code (Python version)
-Project-URL: Homepage, https://github.com/yazelin/claude-code-acp-py
-Project-URL: Repository, https://github.com/yazelin/claude-code-acp-py
-Project-URL: Issues, https://github.com/yazelin/claude-code-acp-py/issues
-Author: yazelin
-License-Expression: MIT
-License-File: LICENSE
-Keywords: acp,agent,anthropic,claude,claude-code,python
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.10
-Requires-Dist: agent-client-protocol>=0.7.0
-Requires-Dist: claude-agent-sdk>=0.1.29
-Description-Content-Type: text/markdown
-
-# Claude Code ACP (Python)
-
-[![PyPI](https://img.shields.io/pypi/v/claude-code-acp)](https://pypi.org/project/claude-code-acp/)
-[![Python](https://img.shields.io/pypi/pyversions/claude-code-acp)](https://pypi.org/project/claude-code-acp/)
-[![License](https://img.shields.io/github/license/yazelin/claude-code-acp-py)](https://github.com/yazelin/claude-code-acp-py/blob/main/LICENSE)
-
-ACP-compatible agent for Claude Code using the Python SDK.
-
-This package bridges the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) with the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/), allowing Claude Code to work with any ACP-compatible client like [Zed](https://zed.dev), Neovim, JetBrains IDEs, etc.
-
-## Features
-
-- Full ACP protocol support
-- Bidirectional communication (permission requests, tool calls)
-- Uses your Claude CLI subscription (no API key needed)
-- Session management (create, fork, resume, list)
-- Multiple permission modes (default, acceptEdits, plan, bypassPermissions)
-
-## Installation
-
-```bash
-pip install claude-code-acp
-```
-
-Or with uv:
-
-```bash
-uv add claude-code-acp
-```
-
-## Requirements
-
-- Python 3.10+
-- Claude CLI installed and authenticated (`claude /login`)
-
-## Usage
-
-### As a standalone ACP server
-
-```bash
-claude-code-acp
-```
-
-### With Zed Editor
-
-Add to your Zed `settings.json`:
-
-```json
-{
-  "agent_servers": {
-    "Claude Code Python": {
-      "type": "custom",
-      "command": "claude-code-acp",
-      "args": [],
-      "env": {}
-    }
-  }
-}
-```
-
-Then open the Agent Panel (`Ctrl+?`) and select "Claude Code Python" from the `+` menu.
-
-### As a library
-
-```python
-import asyncio
-from claude_code_acp import ClaudeAcpAgent
-from acp import run_agent
-
-async def main():
-    agent = ClaudeAcpAgent()
-    await run_agent(agent)
-
-asyncio.run(main())
-```
-
-## How it works
-
-```
-┌─────────────┐     ACP      ┌──────────────────┐    SDK     ┌─────────────┐
-│  Zed/IDE    │ ◄──────────► │ claude-code-acp  │ ◄────────► │ Claude CLI  │
-│ (ACP Client)│   (stdio)    │  (This package)  │            │(Subscription)│
-└─────────────┘              └──────────────────┘            └─────────────┘
-```
-
-## License
-
-MIT

claude_code_acp-0.1.0.dist-info/RECORD

@@ -1,8 +0,0 @@
-claude_code_acp/__init__.py,sha256=CsH-yvcnqCtSci91gwsWeLBpvhYAX1_61QrBSndg2U0,635
-claude_code_acp/__main__.py,sha256=zuAdIOmaCsDeRxj2yIl_qMx-74QFaA3nWiS8gti0og0,118
-claude_code_acp/agent.py,sha256=qos32gnMAilOlz6ebllkmuJZS3UgpbAtAZw58r3SYig,20619
-claude_code_acp-0.1.0.dist-info/METADATA,sha256=aaNmQTUTBgMVFfWKZoUxyedNUkwVc0sLjf-3DIGAOMM,3383
-claude_code_acp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-claude_code_acp-0.1.0.dist-info/entry_points.txt,sha256=cc_pkg_V_1zctD5CUqjATCxglkf5-UArEMfN3q9We-A,57
-claude_code_acp-0.1.0.dist-info/licenses/LICENSE,sha256=5NCM9Q9UTfsn-VyafO7htdlYyPPO8H-NHYrO5UV9sT4,1064
-claude_code_acp-0.1.0.dist-info/RECORD,,