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] public: true(https://agentclientprotocol.com/) (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.