Server

The DeepAgentsServer class is the core of the ACP integration. It wraps DeepAgents with the Agent Client Protocol, enabling communication with IDEs like Zed, JetBrains, and other ACP-compatible clients.

Learn more: For the ACP specification, see agentclientprotocol.com.

Basic Usage

import { DeepAgentsServer } from "deepagents-acp";

const server = new DeepAgentsServer({
  agents: {
    name: "coding-assistant",
    description: "AI coding assistant with filesystem access",
  },
  workspaceRoot: process.cwd(),
});

await server.start();

Quick Start with startServer

import { startServer } from "deepagents-acp";

await startServer({
  agents: {
    name: "my-agent",
    description: "My coding assistant",
  },
});

Multiple Agents

Define multiple agents and let the client select at session creation time:

const server = new DeepAgentsServer({
  agents: [
    {
      name: "code-agent",
      description: "Full-featured coding assistant",
      model: "claude-sonnet-4-5-20250929",
      skills: ["./skills/"],
      memory: ["./.deepagents/AGENTS.md"],
    },
    {
      name: "reviewer",
      description: "Code review specialist",
      systemPrompt: "You are a code review expert...",
    },
  ],
  workspaceRoot: process.cwd(),
  debug: true,
});

Modes

The server supports three operating modes, switchable via slash commands or the ACP session/set_mode request:

Mode	Description
agent	Full autonomous agent with file access
plan	Planning and discussion without file changes
ask	Q&A without file modifications

Slash Commands

Built-in slash commands are available from the IDE prompt:

Command	Description
/plan	Switch to plan mode
/agent	Switch to agent mode
/ask	Switch to ask mode
/clear	Clear conversation context and start fresh
/status	Show session status and loaded skills

Define custom slash commands per agent:

const server = new DeepAgentsServer({
  agents: {
    name: "my-agent",
    commands: [
      { name: "test", description: "Run the project's test suite" },
      { name: "lint", description: "Run linter and fix issues" },
    ],
  },
});

Human-in-the-Loop (Permission Requests)

Configure tools that require user approval before execution:

const server = new DeepAgentsServer({
  agents: {
    name: "safe-agent",
    interruptOn: {
      write_file: true,
      edit_file: true,
      execute: {
        allowedDecisions: ["approve", "edit", "reject"],
      },
    },
  },
});

When a protected tool is invoked, the IDE shows a permission dialog with options: Allow once, Reject, Always allow, Always reject.

ACP Filesystem Backend

When the ACP client advertises fs.readTextFile and fs.writeTextFile capabilities, the server proxies file operations through the client instead of reading/writing directly from disk:

• Unsaved buffer access — reads the editor's current buffer, including unsaved changes
• IDE-tracked modifications — writes go through the IDE, enabling undo and change tracking

Falls back to local FilesystemBackend for operations without ACP equivalents (ls, glob, grep).

Tool Call Enhancements

The server provides rich tool call reporting to the IDE:

• Tool call kinds — categorized using ACP-standard kinds (read, edit, search, execute, think) for appropriate icon display
• File locations — tool calls that operate on files report { path, line } locations, enabling IDEs to follow along in real time
• Raw input/output — tool call notifications include raw arguments and results for transparency

Session Persistence

Sessions are persisted using LangGraph's checkpointer. When loading a session with session/load, the server replays the full conversation history including user messages, agent responses, tool calls, and plan entries.

API Reference