acp-agent-mock

ACP Mock Agent

Mock-agent for the Agent Client Protocol, designed for testing ACP client implementations (IDE plugins, etc.) without connecting to a real AI agent.

Provides a Web UI to manually trigger ACP operations (tool calls, file operations, terminal commands, permission requests) and a session replay engine that replays recorded acp-transport.log files.

Installation

Requires Node.js >= 18.

npm i acp-agent-mock

Running

The agent communicates over stdin/stdout using NDJSON (ACP transport protocol). On startup it also launches a Web UI on a random port — the URL is printed to stderr and shown in the IDE chat.

Add the mock agent to your ACP client configuration:

{
   "agent_servers": {
      "acp-agent-mock": {
         "command": "npx",
         "args": [
            "-y",
            "acp-agent-mock",
            "-acp"
         ]
      }
   }
}

After that, select "acp-agent-mock" in the IDE chat and send any message. The agent will respond with a Web UI link.

Usage

Manual mode

1. Send a message in the IDE chat to the mock agent.
2. The agent responds with a Web UI URL (e.g., http://localhost:54321).
3. Open the Web UI in a browser.
4. Use the UI panels to trigger ACP operations:
   • File System — readTextFile, writeTextFile (results appear as tool calls in the IDE)
   • Terminal — execute shell commands via createTerminal
   • Request Permission — test the permission request flow
   • Session Updates — send message chunks, tool calls, tool call updates, diffs, plans, mode updates
5. Click End Turn when done — the agent completes the prompt and the IDE is ready for the next message.

Session replay

Replay mode lets you re-play a previously recorded ACP session from a transport log file. This is useful for reproducing bugs, regression testing, and demoing ACP features without manual interaction.

Step 1: Get a transport log

The log file is written by the ACP client (IDE plugin). In JetBrains IDEs, find it at:

~/Library/Logs/JetBrains/<product><version>/acp-transport-memory.log    # macOS
~/.local/share/JetBrains/<product><version>/log/acp-transport-memory.log # Linux

The file contains NDJSON lines prefixed with timestamps and direction (IN/OUT):

2026-03-05 14:29:35,529 [  23] FINE - AcpTransport - OUT: {"jsonrpc":"2.0","id":1,"method":"initialize",...}
2026-03-05 14:29:35,659 [  23] FINE - AcpTransport - IN:  {"jsonrpc":"2.0","id":1,"result":{...}}

Step 2: Load the log in Web UI

1. Start the mock agent and open the Web UI (as described above).
2. In the Log Replay panel, paste the contents of the transport log file into the text area.
3. Click Parse Log.
4. The parser extracts all sessions and prompt turns from the log. Select the session you want to replay from the dropdown.

Step 3: Start replay

1. Click Start Replay — the agent enters "armed" mode.
2. Send any message in the IDE chat — the agent will not respond manually but instead replay the first prompt turn from the log, including all tool calls, message chunks, diffs, and permission requests with their original timing.
3. Each subsequent message you send in the IDE triggers the next prompt turn from the log.
4. After all turns are exhausted, the agent falls back to manual mode.
5. Click Stop Replay at any time to abort and return to manual mode.

Replay details

• Inter-message delays from the original session are preserved, so the IDE sees the same timing as the real agent.
• session/update notifications (tool calls, message chunks, plans) are replayed directly.
• session/request_permission requests are sent to the IDE and require the user to respond (accept/reject).
• The sessionId in replayed messages is automatically rewritten to match the current session.