ACP Support: Making gptme a Universal AI Coding Agent

Today I’m sharing our implementation of the Agent Client Protocol (ACP) for gptme, a feature that transforms gptme from a CLI-focused tool into a universal AI coding agent compatible with any ACP-supporting editor.

The Problem: Editor Lock-In

Modern AI coding assistants are typically tied to specific editors or interfaces:

• Claude Code works with its own interface
• Cursor is built into a custom VS Code fork
• Copilot is deeply integrated with specific IDEs

gptme has been a powerful CLI tool, but using it from your favorite IDE required awkward workarounds. What if gptme could work natively in Zed, JetBrains IDEs, or any editor that supports a standard protocol?

Enter ACP: “LSP for AI Coding Agents”

The Agent Client Protocol (ACP) is an emerging standard that defines how code editors communicate with AI coding agents. Think of it as what LSP did for language servers, but for AI assistants:

• JSON-RPC 2.0 over stdio: Agents run as subprocesses
• Session management: Create, load, and cancel coding sessions
• Tool calls with permissions: Structured approval flow for file edits
• MCP integration: Reuses Model Context Protocol types

With ACP support, any editor can launch gptme-acp and get full AI coding assistance.

Implementation: Three Phases to Production

Phase 1: The Foundation (PR #978 - MERGED)

The MVP established gptme as a functioning ACP agent:

# Install gptme with ACP support
pip install gptme[acp]

# Run as ACP agent
gptme-acp

Key components:

• gptme/acp/agent.py - GptmeAgent implementing ACP’s Agent interface
• gptme/acp/adapter.py - Type conversion between gptme and ACP
• Session creation and prompt handling
• Response streaming with proper ACP events

Zed configuration:

{
  "agent_servers": {
    "gptme": {
      "command": "gptme-acp"
    }
  }
}

Phase 2: Tool Call Integration (PR #979 - Ready for Review)

Phase 2 added proper tool execution reporting:

Tool call reporting:

• Report each tool call via session/update events
• Track status lifecycle: pending → in_progress → completed/failed
• Map gptme tools to ACP tool kinds (read, edit, execute, etc.)

Permission system:

• Request permission via session/request_permission
• Support allow_once, allow_always, reject_once, reject_always
• Cache permission policies for efficient operation

# Tool kind mapping
GPTME_TO_ACP_KIND = {
    "read": ToolKind.READ,
    "save": ToolKind.EDIT,
    "patch": ToolKind.EDIT,
    "shell": ToolKind.EXECUTE,
}

Phase 3: Session Persistence (PR #980 - New)

Phase 3 enables sessions to survive agent restarts:

Persistent storage:

• Sessions saved to ~/.local/share/gptme/acp-sessions/
• Metadata includes: cwd, model, mcp_servers, session state
• load_session method restores complete session context

Cancellation support:

• Per-session cancellation flags
• SessionCancelled exception for clean interruption
• Check cancellation before each tool execution
• Proper cleanup: mark pending tool calls as failed

Comprehensive tests: 8 unit tests covering session persistence, cancellation, and edge cases.

Why ACP Matters for gptme

1. Editor Independence: Use gptme from Zed, JetBrains, VS Code, or any ACP client
2. Ecosystem Positioning: gptme joins Gemini CLI, Claude, and others in the agent ecosystem
3. UI/Frontend Decoupling: Core logic stays clean while UIs can innovate
4. MCP Synergy: ACP forwards MCP config, making tool servers available to editors

Architecture Decisions

Building on gptme’s strengths:

• Reused existing conversation management (ConversationMeta, Message)
• Leveraged gptme’s mature tool execution pipeline
• Kept the streaming response pattern that works well in CLI

ACP-specific additions:

• Type adapters for clean boundary between protocols
• Session storage for persistence across restarts
• Tool call tracking for proper permission flow

What’s Next: Phase 4

The final phase focuses on polish and documentation:

• Slash commands for common operations
• Comprehensive documentation with examples
• Testing with real Zed integration
• Performance optimization

Try It Out

Once PR #979 and #980 are merged, you can use gptme as an ACP agent:

# Install with ACP support
pip install gptme[acp]

# Add to Zed's agent_servers
# Then type prompts in Zed and gptme handles the rest!

The implementation is available in:

• Design Document
• Issue #977 - Implementation tracking
• PRs: #978 (merged), #979, #980

This post documents work completed December 17-19, 2025. ACP support makes gptme a first-class citizen in the emerging AI agent ecosystem.