4 min read

Documentation Index

Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt Use this file to discover all available pages before exploring further.

Terminals

Executing and managing terminal commands

The terminal methods allow Agents to execute shell commands within the Client’s environment. These methods enable Agents to run build processes, execute scripts, and interact with command-line tools while providing real-time output streaming and process control.

Checking Support

Before attempting to use terminal methods, Agents MUST verify that the Client supports this capability by checking the Client Capabilities field in the initialize response:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "terminal": true
    }
  }
}

If terminal is false or not present, the Agent MUST NOT attempt to call any terminal methods.

Executing Commands

The terminal/create method starts a command in a new terminal:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "terminal/create",
  "params": {
    "sessionId": "sess_abc123def456",
    "command": "npm",
    "args": ["test", "--coverage"],
    "env": [
      {
        "name": "NODE_ENV",
        "value": "test"
      }
    ],
    "cwd": "/home/user/project",
    "outputByteLimit": 1048576
  }
}

The [Session ID](https://agentclientprotocol.com/protocol/v1/session-setup#session-id) for this request The command to execute Array of command arguments Environment variables for the command.

Each variable has:

name: The environment variable name
value: The environment variable value

Working directory for the command. Must be an absolute path. Maximum number of output bytes to retain. Once exceeded, earlier output is truncated to stay within this limit.

When the limit is exceeded, the Client truncates from the beginning of the output to stay within the limit.

The Client MUST ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit.

The Client returns a Terminal ID immediately without waiting for completion:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "terminalId": "term_xyz789"
  }
}

This allows the command to run in the background while the Agent performs other operations.

After creating the terminal, the Agent can use the terminal/wait_for_exit method to wait for the command to complete.

<Note> The Agent MUST release the terminal using terminal/release when it’s no longer needed.

Embedding in Tool Calls

Terminals can be embedded directly in tool calls to provide real-time output to users:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_002",
      "title": "Running tests",
      "kind": "execute",
      "status": "in_progress",
      "content": [
        {
          "type": "terminal",
          "terminalId": "term_xyz789"
        }
      ]
    }
  }
}

When a terminal is embedded in a tool call, the Client displays live output as it’s generated and continues to display it even after the terminal is released.

Getting Output

The terminal/output method retrieves the current terminal output without waiting for the command to complete:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "terminal/output",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

The Client responds with the current output and exit status (if the command has finished):

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "output": "Running tests...\n✓ All tests passed (42 total)\n",
    "truncated": false,
    "exitStatus": {
      "exitCode": 0,
      "signal": null
    }
  }
}

The terminal output captured so far Whether the output was truncated due to byte limits Present only if the command has exited. Contains:

exitCode: The process exit code (may be null)
signal: The signal that terminated the process (may be null)

Waiting for Exit

The terminal/wait_for_exit method returns once the command completes:

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "terminal/wait_for_exit",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

The Client responds once the command exits:

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "exitCode": 0,
    "signal": null
  }
}

The process exit code (may be null if terminated by signal) The signal that terminated the process (may be null if exited normally)

Killing Commands

The terminal/kill method terminates a command without releasing the terminal:

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "terminal/kill",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

After killing a command, the terminal remains valid and can be used with:

terminal/output to get the final output
terminal/wait_for_exit to get the exit status

The Agent MUST still call terminal/release when it’s done using it.

Building a Timeout

Agents can implement command timeouts by combining terminal methods:

Create a terminal with terminal/create
Start a timer for the desired timeout duration
Concurrently wait for either the timer to expire or terminal/wait_for_exit to return
If the timer expires first:
- Call terminal/kill to terminate the command
- Call terminal/output to retrieve any final output
- Include the output in the response to the model
Call terminal/release when done

Releasing Terminals

The terminal/release kills the command if still running and releases all resources:

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "terminal/release",
  "params": {
    "sessionId": "sess_abc123def456",
    "terminalId": "term_xyz789"
  }
}

After release the terminal ID becomes invalid for all other terminal/* methods.

If the terminal was added to a tool call, the client SHOULD continue to display its output after release.

Last updated Oct 08, 2026