What is ACP

Overview

ACP (Agent Client Protocol) is a standardized stdio protocol that allows IDEs and editors to drive an AI Agent via NDJSON streams over stdin/stdout. Langcli implements a full ACP agent endpoint that can be directly invoked by ACP-supporting clients such as Zed, Cursor, VSCode, and others.

Core Features

Session Management: Create / Resume / Load / Fork / Close sessions
History Replay: Automatically load and replay conversation history when resuming a session
Permission Bridging: Map ACP client permission decisions to Langcli's tool permission system
Slash Commands & Skills: Load the real command list, supporting prompt-type skills like /commit, /review
Context Window Tracking: Precise usage_update with model prefix matching
Prompt Queuing: Support sending multiple prompts concurrently with automatic queue processing
Mode Switching: auto / default / acceptEdits / plan / dontAsk / bypassPermissions
Model Switching: Switch AI models at runtime

Architecture

┌──────────────┐    NDJSON/stdio    ┌─────────────────────────┐
│  Zed / IDE   │ ◄────────────────► │  Langcli ACP Agent      │
│  (Client)    │   stdin / stdout   │  (Agent)                │
└──────────────┘                    │                         │
                                    │  entry.ts               │ ← stdio → NDJSON stream
                                    │  agent.ts               │ ← ACP protocol handler
                                    │  bridge.ts              │ ← SDKMessage → ACP SessionUpdate
                                    │  permissions.ts         │ ← Permission bridging
                                    │  utils.ts               │ ← Utilities
                                    │                         │
                                    │  QueryEngine            │ ← Internal query engine
                                    └─────────────────────────┘

ACP Protocol Support Matrix

Method	Status	Description
`initialize`	✅	Return agent info and capabilities
`authenticate`	✅	No authentication required (self-hosted)
`newSession`	✅	Create a new session
`resumeSession`	✅	Resume an existing session (with history replay)
`loadSession`	✅	Load a specified session (with history replay)
`listSessions`	✅	List available sessions
`forkSession`	✅	Fork a session
`closeSession`	✅	Close a session
`prompt`	✅	Send a message with queue support
`cancel`	✅	Cancel current/queued prompts
`setSessionMode`	✅	Switch permission mode
`setSessionModel`	✅	Switch AI model
`setSessionConfigOption`	✅	Dynamically modify configuration

SessionUpdate Types

Type	Status	Description
`agent_message_chunk`	✅	Assistant text message
`agent_thought_chunk`	✅	Thought/reasoning content
`user_message_chunk`	✅	User message (history replay)
`tool_call`	✅	Tool call started
`tool_call_update`	✅	Tool call result/status update
`usage_update`	✅	Token usage + context window
`plan`	✅	TodoWrite → plan entries
`available_commands_update`	✅	Slash commands & skills list
`current_mode_update`	✅	Mode switch notification
`config_option_update`	✅	Config update notification

Overview

Core Features

Architecture

ACP Protocol Support Matrix

SessionUpdate Types

Table of Contents