1---
2date: 2025-08-28 15:34:28 PDT
3researcher: Mikayla Maki
4git_commit: 565782a1c769c90e58e012a80ea1c2d0cfcdb837
5branch: claude-experiments
6repository: zed
7topic: "Custom Slash Commands for Agent Client Protocol"
8tags: [research, codebase, acp, slash-commands, claude-code, protocol-extension]
9status: complete
10last_updated: 2025-08-28
11last_updated_by: Mikayla Maki
12---
13
14# Research: Custom Slash Commands for Agent Client Protocol
15
16**Date**: 2025-08-28 15:34:28 PDT
17**Researcher**: Mikayla Maki
18**Git Commit**: 565782a1c769c90e58e012a80ea1c2d0cfcdb837
19**Branch**: claude-experiments
20**Repository**: zed
21
22## Research Question
23
24We're adding support for custom slash commands to Agent Client Protocol for the **agent panel** (not assistant 1/text threads). The client should be able to:
25
26- List available commands
27- Run a command with arguments (check Claude Code behavior)
28
29In the Claude Code ACP adapter, we want implement the _agent_ side of the protocol:
30
31- List commands by reading out of the `.claude/commands` directory
32- Run commands via the SDK
33
34We need to update the protocol to support the new RPCs for listing and running commands.
35We need to understand how to run commands via the SDK.
36
37**Important Note**: This is for the agent panel UX, NOT the existing assistant/text thread slash commands. The existing slash command infrastructure is for assistant 1/text threads and is not relevant to this implementation.
38
39## Summary
40
41The research reveals the architecture needed for implementing custom slash commands in the **agent panel** via ACP:
42
43**Agent Panel Architecture**: Separate UI system from assistant/text threads with dedicated components (`AgentPanel`, `AcpThreadView`) and message handling through ACP protocol integration.
44
45**ACP Protocol**: JSON-RPC based with clear patterns for adding new RPC methods through request/response enums, method dispatch, and capability negotiation. Handles session management, tool calls, and real-time message streaming.
46
47**Claude Commands Structure**: Markdown-based command definitions in `.claude/commands/` with consistent format, metadata, and programmatic parsing potential.
48
49**SDK Integration**: Claude Code ACP adapter bridges ACP protocol with Claude SDK, providing tool execution and session management through MCP servers.
50
51**Note**: The existing Claude Code slash command system (`SlashCommand` trait, `assistant_slash_command` crate) is **not relevant** - that's for assistant 1/text threads. The agent panel needs its own custom command implementation.
52
53## Detailed Findings
54
55### Agent Panel Architecture
56
57**Core Infrastructure** (`crates/agent_ui/`):
58
59- `agent_panel.rs:24` - Main `AgentPanel` struct and UI component
60- `acp/thread_view.rs:315` - `AcpThreadView` component for individual agent conversations
61- `acp/message_editor.rs` - Message input component with slash command integration for agent panel
62- `acp.rs` - ACP module entry point connecting to external ACP agents
63
64**Agent Panel vs Assistant Distinction**:
65
66The agent panel is **completely separate** from the assistant/text thread system:
67- Agent panel uses ACP (Agent Client Protocol) for external agent communication
68- Assistant uses internal Zed slash commands and text thread editors
69- Different UI components, different input handling, different protocol integration
70
71**ACP Integration Flow**:
72
731. External ACP agent process spawned via `agent_servers/src/acp.rs:63-76`
742. JSON-RPC connection established over stdin/stdout at line 84
753. Protocol initialization with capability negotiation at line 131
764. Sessions created via `new_session()` request for isolated conversations
775. User input converted to `PromptRequest` and sent to ACP agent
786. Agent responses stream back as `SessionUpdate` notifications
797. UI updates processed in `AcpThread::handle_session_update()`
80
81**Current Input Handling**:
82
83- Message composition through `MessageEditor` and specialized ACP message editor
84- Standard chat input without custom command support currently
85- Integration with model selector, context strip, and profile management
86
87### Agent Client Protocol RPC Patterns
88
89**Core Structure** (`agentic-coding-protocol/`):
90
91- JSON-RPC based bidirectional communication
92- Type-safe request/response enums with static dispatch
93- Capability negotiation for feature opt-in
94- Auto-generated JSON Schema from Rust types
95
96**RPC Method Pattern**:
97
981. Define request/response structs with `#[derive(Serialize, Deserialize, JsonSchema)]`
992. Add method name constant: `const NEW_METHOD_NAME: &str = "new/method"`
1003. Add variants to `ClientRequest`/`AgentRequest` enums
1014. Update trait definition with async method signature
1025. Add to dispatch logic in `decode_request()` and `handle_request()`
103
104**Existing Methods**:
105
106- `initialize` - Capability negotiation and authentication
107- `session/new`, `session/load` - Session management
108- `session/prompt` - Message processing
109- `fs/read_text_file`, `fs/write_text_file` - File operations
110- `session/request_permission` - Permission requests
111
112### .claude/commands Directory Structure
113
114**Format**: Markdown files with consistent structure:
115
116```markdown
117# Command Name
118
119[Description]
120
121## Initial Response
122
123[Standardized first response]
124
125## Process Steps
126
127### Step 1: [Phase Name]
128
129[Instructions]
130
131## Important Guidelines
132
133[Constraints and behaviors]
134```
135
136**Metadata Extraction Points**:
137
138- H1 title for command name and description
139- "Initial Response" section for invocation behavior
140- Sequential process steps under "Process Steps"
141- Checkbox lists (`- [ ]`, `- [x]`) for progress tracking
142- Code blocks with executable commands
143
144**Command Categories**:
145
146- Development workflow: `create_plan.md`, `implement_plan.md`, `validate_plan.md`, `commit.md`
147- Research: `research_codebase.md`, `debug.md`
148- Project management: `ralph_plan.md`, `founder_mode.md`
149
150### Claude Code ACP Adapter Implementation
151
152**Architecture** (`claude-code-acp/src/`):
153
154- `acp-agent.ts` - Main `ClaudeAcpAgent` implementing ACP Agent interface
155- `mcp-server.ts` - Internal MCP server for file operations and permissions
156- `tools.ts` - Tool conversion between Claude and ACP formats
157- Session management with unique IDs and Claude SDK `Query` objects
158
159**Integration Pattern**:
160
161```typescript
162let q = query({
163 prompt: input,
164 options: {
165 cwd: params.cwd,
166 mcpServers: { acp: mcpServerConfig },
167 allowedTools: ["mcp__acp__read"],
168 disallowedTools: ["Read", "Write", "Edit", "MultiEdit"],
169 },
170});
171```
172
173**Tool Execution Flow**:
174
1751. ACP client makes tool request
1762. Claude ACP agent converts to Claude SDK format
1773. Internal MCP server proxies to ACP client capabilities
1784. Results converted back to ACP format
179
180## Code References
181
182- `crates/agent_ui/src/agent_panel.rs:24` - Main AgentPanel component
183- `crates/agent_ui/src/acp/thread_view.rs:315` - AcpThreadView UI component
184- `crates/agent_ui/src/acp/message_editor.rs` - Agent panel message input
185- `crates/agent_servers/src/acp.rs:63-162` - ACP connection establishment
186- `crates/acp_thread/src/acp_thread.rs:826` - ACP thread creation
187- `agentic-coding-protocol/rust/agent.rs:604-610` - ACP request enum pattern
188- `agentic-coding-protocol/rust/acp.rs:355-371` - Method dispatch logic
189- `claude-code-acp/src/acp-agent.ts:1-500` - ACP adapter implementation
190- `.claude/commands/*.md` - Command definition files
191
192## Architecture Insights
193
194**Agent Panel System**: Completely separate from assistant/text threads, uses ACP protocol for external agent communication with JSON-RPC over stdin/stdout, manages sessions with unique IDs, and provides real-time message streaming with UI updates.
195
196**ACP Protocol**: Designed for extensibility with capability negotiation, type safety through Rust enums, symmetric bidirectional design, and JSON-RPC foundation. Handles tool calls, permissions, and session management.
197
198**Command Definitions**: Human-readable markdown with programmatically parseable structure, consistent metadata patterns, and workflow automation framework stored in `.claude/commands/`.
199
200**Integration Patterns**: Claude Code ACP adapter provides proven pattern for bridging protocols, MCP servers enable tool execution proxying, session management handles concurrent interactions. Agent panel needs new command integration separate from existing slash commands.
201
202## Implementation Recommendations
203
204### 1. Protocol Extension for Custom Commands
205
206Add new RPC methods to ACP schema following existing patterns in `agentic-coding-protocol/rust/`:
207
208```rust
209// New request types
210pub struct ListCommandsRequest {
211 pub session_id: SessionId,
212}
213
214pub struct RunCommandRequest {
215 pub session_id: SessionId,
216 pub command: String,
217 pub args: Option<String>,
218}
219
220// Response types
221pub struct ListCommandsResponse {
222 pub commands: Vec<CommandInfo>,
223}
224
225pub struct CommandInfo {
226 pub name: String,
227 pub description: String,
228 pub requires_argument: bool,
229}
230```
231
232Add to request/response enums and implement in dispatch logic similar to existing ACP methods.
233
234### 2. Agent Panel UI Integration
235
236**Option A**: Extend ACP Message Editor
237- Modify `crates/agent_ui/src/acp/message_editor.rs` to detect custom commands
238- Add command completion/suggestion UI similar to existing patterns
239- Trigger custom command execution through ACP protocol
240
241**Option B**: New Command Interface
242- Create dedicated command input component in agent panel
243- Separate from regular message input to provide distinct UX
244- Integrate with `AcpThreadView` for command results display
245
246### 3. ACP Agent Implementation
247
248In Claude Code ACP adapter (`claude-code-acp/src/acp-agent.ts`):
249
250```typescript
251async listCommands(request: ListCommandsRequest): Promise<ListCommandsResponse> {
252 // Read .claude/commands directory
253 // Parse markdown files for metadata
254 // Return CommandInfo array
255}
256
257async runCommand(request: RunCommandRequest): Promise<RunCommandResponse> {
258 // Find command definition in .claude/commands/
259 // Execute via Claude SDK query with command content
260 // Stream results back via session notifications using existing session update mechanism
261}
262```
263
264### 4. Command Parsing and Execution
265
266Implement markdown parser for `.claude/commands/*.md`:
267
268```typescript
269function parseCommandFile(content: string): CommandInfo {
270 // Extract H1 title for name/description
271 // Find "Initial Response" section
272 // Parse metadata and requirements
273 // Return structured command info
274}
275```
276
277Execute commands by sending command content as system prompt to Claude SDK, similar to existing ACP query patterns.
278
279## Open Questions
280
2811. **Agent Panel UX**: Should custom commands be integrated into the existing message input or as a separate command interface?
282
2832. **Command Arguments**: How should complex command arguments be structured and validated in the agent panel context?
284
2853. **Command Context**: Should commands have access to current ACP session state, file context, or conversation history?
286
2874. **Command Discovery**: Should commands be cached or re-read on each listing request? How does this integrate with ACP session lifecycle?
288
2895. **Command Execution**: Should commands run in isolated contexts or share ACP session state?
290
2916. **Error Handling**: What's the appropriate error handling strategy for command parsing and execution failures in the agent panel?
292
2937. **UI Integration**: How should command execution progress and results be displayed within the `AcpThreadView` component?
294
295###### FINAL CLAUDE PROMPT:
296
297⏺ I've completed comprehensive research on adding custom
298slash commands to the Agent Client Protocol for the
299**agent panel** (NOT assistant/text threads). Here's what
300I found:
301
302Key Findings
303
304Agent Panel Architecture: The agent panel is completely
305separate from assistant/text threads, using ACP protocol
306for external agent communication via JSON-RPC over
307stdin/stdout. It has dedicated UI components like
308AgentPanel and AcpThreadView.
309
310ACP Protocol Patterns: The protocol uses JSON-RPC with
311type-safe request/response enums. Adding new RPC methods
312follows a clear pattern: define structs, add to enums,
313update dispatch logic. Handles sessions, tool calls, and
314real-time streaming.
315
316.claude/commands Structure: Commands are defined as
317structured Markdown files with consistent format -
318perfect for programmatic parsing. Each contains metadata,
319process steps, and execution guidelines.
320
321SDK Integration: The Claude Code ACP adapter already
322bridges ACP with the Claude SDK through MCP servers,
323providing a proven pattern for command execution.
324
325**IMPORTANT**: The existing Claude Code slash command
326system (SlashCommand trait, assistant_slash_command crate)
327is NOT relevant - that's for assistant 1/text threads.
328The agent panel needs its own custom command
329implementation.
330
331Implementation Approach
332
333You'll need to:
334
3351. Extend ACP Protocol: Add ListCommandsRequest/Response
336 and RunCommandRequest/Response to the schema
3372. Agent Panel UI: Integrate custom commands into agent
338 panel message input or create separate command interface
3393. Parse Command Definitions: Read .claude/commands/\*.md
340 files and extract metadata (name, description,
341 requirements)
3424. Execute Commands: Run commands via Claude SDK queries
343 through existing ACP session mechanism
3445. Handle Streaming: Use ACP's session notification
345 system to stream command progress to AcpThreadView
346
347The research document is saved at thoughts/shared/researc
348h/2025-08-28_15-34-28_custom-slash-commands-acp.md with
349detailed implementation recommendations, code references,
350and open questions for your consideration.
351
352###### STATS ON PROMPT TO GENERATE THIS DOCUMENT:
353
354Total cost: $2.87
355Total duration (API): 12m 59.0s
356Total duration (wall): 6m 52.2s
357Total code changes: 242 lines added, 0 lines removed
358Usage by model:
359claude-3-5-haiku: 4.3k input, 175 output, 0 cache read, 0 cache write
360claude-sonnet: 2.9k input, 31.3k output, 4.8m cache read, 256.1k cache write