Pi ACP Adapter

https://github.com/svkozak/pi-acp
Admin
Pi ACP Adapter is an Agent Client Protocol (ACP) adapter that enables communication with the...
Tokens:36,859
Snippets:504
Trust Score:9.1
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Verify Installation and PATH

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/errors.md

Installs the agent and verifies the executable is available on the system PATH.

```bash
npm install -g @earendil-works/pi-coding-agent
which pi  # Verify it's on PATH
```

--------------------------------

### Global Install and Configuration

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Install pi-acp globally and configure the agent server.

```bash
npm install -g pi-acp
```

```json
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "pi-acp",
      "args": [],
      "env": {}
    }
  }
```

--------------------------------

### Install pi-acp from Source

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Clones the repository and builds the project locally.

```bash
git clone https://github.com/svkozak/pi-acp.git
cd pi-acp
npm install
npm run build
# Run via node dist/index.js
```

--------------------------------

### Example session/new request

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

A JSON-RPC request example for creating a new session.

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "session/new",
  "params": {
    "cwd": "/home/user/my-project"
  }
}
```

--------------------------------

### Install pi-coding-agent

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Install the required pi-coding-agent globally.

```bash
npm install -g @earendil-works/pi-coding-agent
```

--------------------------------

### Configure Zed with Global Installation

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Uses a globally installed pi-acp package. Requires running 'npm install -g pi-acp' first.

```json
{
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "pi-acp",
      "args": [],
      "env": {
        "PI_ACP_ENABLE_EMBEDDED_CONTEXT": "true"
      }
    }
  }
}
```

```bash
npm install -g pi-acp
```

--------------------------------

### Run project tests

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Commands to install dependencies and execute the test suite.

```bash
cd /path/to/pi-acp
npm install
npm run test
```

--------------------------------

### JSON-RPC Session List Example

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

A concrete JSON-RPC request example for the session/list endpoint.

```json
{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "session/list",
  "params": {
    "cwd": "/home/user/my-project"
  }
}
```

--------------------------------

### Install pi-acp Globally

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Installs the pi-acp executable to the global npm bin directory.

```bash
npm install -g pi-acp
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Example configuration including the PI_ACP_ENABLE_EMBEDDED_CONTEXT environment variable.

```json
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "node",
      "args": ["/path/to/pi-acp/dist/index.js"],
      "env": {
          "PI_ACP_ENABLE_EMBEDDED_CONTEXT": "true",
      }
    }
  }
```

--------------------------------

### Slash Command Priority Example

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Demonstrates the precedence of project-scoped prompts over global prompts when names collide.

```text
~/.pi/agent/prompts/refactor.md        (global)
<cwd>/.pi/prompts/refactor.md          (project) ← Used (takes priority)
```

--------------------------------

### Slash Command Directory Structures

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Examples of flat and nested directory structures for organizing prompt files.

```text
~/.pi/agent/prompts/
├── refactor.md
├── test.md
└── debug.md
```

```text
~/.pi/agent/prompts/
├── security/
│   ├── audit.md
│   └── review.md
├── testing/
│   ├── unit.md
│   └── integration.md
└── refactor.md
```

--------------------------------

### Slash Command File Structure Example

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Demonstrates how nested markdown files are mapped to slash command names.

```text
~/.pi/agent/prompts/
├── refactor.md
├── security/
│   └── audit.md
└── testing/
    └── unit-tests.md
```

--------------------------------

### Perform manual smoke test

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Starts the development server and sends a JSON-RPC initialize request via netcat.

```bash
npm run dev
# In another terminal:
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | nc localhost 9999
```

--------------------------------

### Check pi version

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Verifies the installed version of the pi agent.

```bash
pi --version
```

--------------------------------

### Install pi-acp Locally

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Adds pi-acp as a development dependency for the current project.

```bash
npm install --save-dev pi-acp
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Standard npm scripts for installing dependencies, running the development server, building, linting, and testing.

```bash
npm install
npm run dev        # run from src via tsx
npm run build
npm run lint
npm run test
```

--------------------------------

### Get Commands Method

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Retrieves available slash commands and skills from pi.

```typescript
async getCommands(): Promise<unknown>
```

--------------------------------

### Spawn process with shell detection

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Example of integrating shell detection into child_process.spawn configuration.

```typescript
const cmd = getPiCommand(params.piCommand)
const child = spawn(cmd, ['--mode', 'rpc'], {
  shell: shouldUseShellForPiCommand(cmd)
})
```

--------------------------------

### Usage Example: expandSlashCommand

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Demonstrates how to define commands and expand a slash command prefix within a user message.

```typescript
const commands = [
  { 
    name: 'refactor', 
    description: 'Refactor code', 
    content: '# Refactor\nCarefully refactor the code...' 
  }
]

const input = '/refactor Plus these changes: fix variable names'

const result = expandSlashCommand(input, commands)
// {
//   message: '# Refactor\nCarefully refactor the code...\n\nPlus these changes: fix variable names',
//   expanded: true
// }
```

--------------------------------

### Load Slash Commands Usage Example

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Demonstrates how to invoke the loadSlashCommands function and the structure of the returned command objects.

```typescript
const commands = loadSlashCommands('/home/user/project')
// [
//   { name: 'refactor', description: 'Refactor code', content: '# Refactor...' },
//   { name: 'security-audit', description: 'Security audit', content: '# Security Audit...' }
// ]
```

--------------------------------

### Get available models

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Queries the available models configured in the user's environment.

```typescript
async getAvailableModels(): Promise<unknown>
```

```typescript
{
  models: [
    { provider: 'anthropic', id: 'claude-opus', name: 'Claude 3 Opus' },
    { provider: 'openai', id: 'gpt-4', name: 'GPT-4' }
  ]
}
```

--------------------------------

### Configure Zed with npx

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Loads the latest version of pi-acp directly from npm without requiring a global installation.

```json
{
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "pi-acp"],
      "env": {}
    }
  }
}
```

--------------------------------

### SessionStore Usage Example

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session-store.md

Demonstrates basic CRUD operations including upserting, retrieving, and deleting sessions using the SessionStore class.

```typescript
const store = new SessionStore()

// Create a new session
store.upsert({
  sessionId: 'sess-001',
  cwd: '/home/user/my-project',
  sessionFile: '/home/user/.pi/agent/sessions/sess-001.jsonl'
})

// Retrieve it later
const session = store.get('sess-001')
console.log(session?.cwd)  // '/home/user/my-project'

// Update (e.g., after loading)
store.upsert({
  sessionId: 'sess-001',
  cwd: '/home/user/my-project',
  sessionFile: '/home/user/.pi/agent/sessions/sess-001.jsonl'
})
// updatedAt is automatically refreshed

// Remove
store.delete('sess-001')
const removed = store.get('sess-001')
console.log(removed)  // null
```

--------------------------------

### Configure pi-acp with npx

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Use npx to run the latest version of pi-acp without a global installation.

```json
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "pi-acp"],
      "env": {}
    }
  }
```

--------------------------------

### Simple Slash Command Markdown

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Example of a simple command defined in a markdown file, which is triggered by the filename.

```markdown
# Refactor Code

Carefully refactor the provided code, focusing on:
- Clarity and readability
- Performance where applicable
- Maintaining existing behavior
- Type safety (if TypeScript)

Do not over-engineer or add unnecessary features.
```

--------------------------------

### Authenticate with ACP Registry

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Use this command to launch the pi agent in a terminal for interactive login and setup.

```bash
pi-acp --terminal-login
```

--------------------------------

### Execute pi-acp with Custom Installation Path

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Override the default pi command path using the PI_ACP_PI_COMMAND environment variable.

```bash
PI_ACP_PI_COMMAND=/opt/my-pi/bin/pi-custom pi-acp
# Uses: spawn('/opt/my-pi/bin/pi-custom', ['--mode', 'rpc'], { shell: false })
```

```batch
set PI_ACP_PI_COMMAND=C:\my-pi\pi-custom.cmd
pi-acp
# Uses: spawn('C:\my-pi\pi-custom.cmd', ['--mode', 'rpc'], { shell: true })
```

--------------------------------

### Invoke a custom slash command

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Example of triggering a custom command from the ACP client.

```text
/code-review Especially focus on error handling
```

--------------------------------

### Multi-level Slash Command Markdown

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Example of a nested command structure where the directory path influences the command name.

```markdown
# Security Audit

Review the provided code for security vulnerabilities:
- SQL injection risks
- XSS vulnerabilities
- Authentication flaws
- Data exposure
```

--------------------------------

### Bash Output Streaming Update

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Example of an incremental update event for bash tool output streaming.

```typescript
{
  sessionUpdate: 'tool_call_update',
  toolCallId: 'bash-456',
  _meta: {
    terminal_output: { toolCallId: 'bash-456', delta: 'Building...\n' }
  }
}
```

--------------------------------

### Override pi command via environment variable

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Example of setting the command path via shell environment variable.

```bash
PI_ACP_PI_COMMAND=/path/to/custom/pi pi-acp
```

--------------------------------

### Build and Configure from Source

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Build the project from source and point the ACP client to the local index.js.

```bash
npm install
npm run build
```

```json
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "node",
      "args": ["/path/to/pi-acp/dist/index.js"],
      "env": {}
    }
  }
```

--------------------------------

### initialize

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Initializes the connection between the client and the adapter.

```APIDOC
## initialize

### Description
Establishes the connection and retrieves adapter capabilities.

### Method
JSON-RPC Request

### Request
`{"method": "initialize"}`

### Response
- **capabilities** (object) - The supported features of the adapter.
```

--------------------------------

### Setting startup information

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Configures a prelude message to be emitted upon the first prompt, useful for providing initial context.

```typescript
setStartupInfo(text: string): void
```

--------------------------------

### setStartupInfo(text: string)

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Sets a prelude message to be emitted on the first prompt.

```APIDOC
## setStartupInfo(text: string)

### Description
Sets a prelude message (e.g., startup info, version, skills) to be emitted on the first prompt. Useful for displaying context to the user on session start.

### Parameters
- **text** (string) - Required - Markdown text to emit as first message chunk
```

--------------------------------

### Get Messages Method

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Retrieves the full conversation history as a promise.

```typescript
async getMessages(): Promise<unknown>
```

```typescript
const data = await proc.getMessages()
// { messages: [{role: 'user', content: '...', ...}, ...] }
```

--------------------------------

### sendStartupInfoIfPending

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Sends the startup info if it hasn't been sent yet. This is typically called after session creation to ensure clients receive startup information even if they do not send an initial prompt.

```APIDOC
## sendStartupInfoIfPending()

### Description
Sends the startup info if it hasn't been sent yet. Called after session creation to ensure clients see it even if they don't send a prompt.

### Signature
`sendStartupInfoIfPending(): Promise<void>`
```

--------------------------------

### get(sessionId: string): PiAcpSession

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Retrieves a registered session by ID.

```APIDOC
## Method: get

### Description
Retrieves a registered session by ID. Throws if not found.

### Parameters
- **sessionId** (string) - Required - Session ID

### Returns
- **PiAcpSession** - The requested session instance

### Throws
- **RequestError.invalidParams** - If session not found
```

--------------------------------

### session/new

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Creates a new session and spawns the pi subprocess.

```APIDOC
## session/new

### Description
Creates a new session, spawns the pi subprocess, and returns the session ID and initial state.

### Method
JSON-RPC Request

### Response
- **sessionId** (string) - Unique identifier for the session.
- **state** (object) - The initial state of the session.
```

--------------------------------

### Get default pi command

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Retrieves the platform-specific default executable name.

```typescript
const cmd = defaultPiCommand()
// On Windows: 'pi.cmd'
// On Unix: 'pi'
```

--------------------------------

### get(sessionId: string)

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session-store.md

Retrieves metadata for a specific session ID from the store.

```APIDOC
## get(sessionId: string)

### Description
Retrieves stored metadata for a session. Returns `null` if the session ID is not found.

### Parameters
- **sessionId** (string) - Required - The unique identifier for the session.

### Returns
- **StoredSession | null** - Returns an object containing `sessionId`, `cwd`, `sessionFile`, and `updatedAt` if found, otherwise null.
```

--------------------------------

### Configure packages setting

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Define a list of npm packages or local paths to load as extensions.

```json
{
  "packages": [
    "npm:@org/extension-package",
    "/local/path/to/extension"
  ]
}
```

--------------------------------

### Create and Use a Session

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Initializes the agent, creates a new session, sends a prompt, and configures session options.

```typescript
// 1. Initialize (handshake)
const init = await agent.initialize({ protocolVersion: 1 })

// 2. Create new session
const session = await agent.newSession({ cwd: '/home/user/project' })
console.log(session.sessionId)  // 'abc-123'

// 3. Send prompt and stream responses
const result = await agent.prompt({
  sessionId: session.sessionId,
  prompt: { content: [{ type: 'text', text: 'Write a test' }] }
})
// Receives session/update notifications during execution
// Returns with stopReason: 'end_turn'

// 4. Set model
await agent.setSessionConfigOption({
  sessionId: session.sessionId,
  configId: 'model',
  value: 'anthropic/claude-opus'
})
```

--------------------------------

### initialize

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Initiates the protocol handshake and performs capability negotiation between the client and the agent.

```APIDOC
## JSON-RPC Method: initialize

### Description
Initiates protocol handshake and capability negotiation between the client and the pi-acp agent.

### Request Parameters
- **protocolVersion** (number) - Required - Must be 1.
- **clientCapabilities** (object) - Optional - Client-side capabilities, including optional _meta fields like 'terminal-auth'.

### Request Example
{
  "jsonrpc": "2.0",
  "id": "req-uuid",
  "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientCapabilities": {
      "_meta": { "terminal-auth": true }
    }
  }
}

### Response
#### Success Response
- **protocolVersion** (number) - The protocol version (1).
- **agentInfo** (object) - Metadata about the agent (name, title, version).
- **authMethods** (array) - List of supported authentication methods.
- **agentCapabilities** (object) - Capabilities supported by the agent, including session, prompt, and mcp capabilities.

#### Response Example
{
  "jsonrpc": "2.0",
  "id": "req-uuid",
  "result": {
    "protocolVersion": 1,
    "agentInfo": {
      "name": "pi-acp",
      "title": "pi ACP adapter",
      "version": "0.0.33"
    },
    "authMethods": [
      { "type": "terminal", "name": "Terminal Auth" }
    ],
    "agentCapabilities": {
      "loadSession": true,
      "mcpCapabilities": { "http": false, "sse": false },
      "promptCapabilities": {
        "image": true,
        "audio": false,
        "embeddedContext": false
      },
      "sessionCapabilities": {
        "list": {},
        "delete": {}
      }
    }
  }
}
```

--------------------------------

### Configure Pi Settings

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Define global settings in the agent configuration file to control startup behavior and skill command availability.

```json
{
  "quietStartup": false,
  "enableSkillCommands": false
}
```

--------------------------------

### session/new

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Creates a new ACP session and initializes a fresh pi subprocess.

```APIDOC
## session/new

### Description
Creates a new ACP session with a fresh pi subprocess. This method initializes the session environment and fetches initial state including available models and modes.

### Method
session/new

### Request Body
- **cwd** (string) - Required - Absolute path for the session working directory.
- **mcpServers** (McpServer[]) - Optional - List of MCP servers.

### Request Example
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "session/new",
  "params": {
    "cwd": "/home/user/my-project"
  }
}

### Response
#### Success Response
- **sessionId** (string) - Unique session identifier.
- **configOptions** (SessionConfigOption[]) - Model and thinking level selectors.
- **models** (object) - Available models and current model ID.
- **modes** (object) - Available modes and current mode ID.
- **_meta** (object) - Startup information including pi version and context.
```

--------------------------------

### Initialize SessionStore

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session-store.md

Instantiate the store using either the default path or a custom file location.

```typescript
const store = new SessionStore()  // Uses default path

const customStore = new SessionStore('/tmp/custom-session-map.json')
```

--------------------------------

### Pi Error Response Signature

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/errors.md

Example of an error response object emitted by the Pi RPC protocol.

```json
{
  "type": "response",
  "id": "req-123",
  "command": "set_model",
  "success": false,
  "error": "Unknown model: invalid/model-id"
}
```

--------------------------------

### initialize

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Handles the ACP initialize request to establish protocol version and agent capabilities.

```APIDOC
## Method: initialize

### Description
Handles the ACP initialize request sent by the client. Returns protocol version, agent info, and declared capabilities.

### Parameters
- **params** (InitializeRequest) - Required - Contains client protocol version and capabilities.

### Returns
- **InitializeResponse** - Contains protocolVersion, agentInfo, authMethods, and agentCapabilities.

### Example
```typescript
const response = await agent.initialize({
  protocolVersion: 1,
  clientCapabilities: { ... }
})
```
```

--------------------------------

### Get Session Map Path

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Retrieves the file system path to the session map JSON file.

```typescript
function getPiAcpSessionMapPath(): string
```

--------------------------------

### Check Startup Info Status

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Method signature for sending startup information if it remains pending after session creation.

```typescript
sendStartupInfoIfPending(): Promise<void>
```

--------------------------------

### Configure Zed with Local Build

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Points to a local build of the pi-acp project. Requires manual build steps.

```json
{
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "node",
      "args": ["/path/to/pi-acp/dist/index.js"],
      "env": {}
    }
  }
}
```

```bash
cd /path/to/pi-acp && npm install && npm run build
```

--------------------------------

### Configure quietStartup setting

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Suppress verbose startup information in the pi-acp logs.

```json
{
  "quietStartup": true
}
```

--------------------------------

### Create a new session

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/INDEX.md

Initializes a new agent session with a specified working directory.

```typescript
const session = await agent.newSession({ cwd: '/home/user/project' })
```

--------------------------------

### Get session state

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Queries the current session state including model, thinking level, and message count.

```typescript
async getState(): Promise<unknown>
```

```typescript
{
  sessionId: 'abc-123',
  sessionFile: '/home/user/.pi/agent/sessions/abc-123.jsonl',
  messageCount: 5,
  model: { provider: 'anthropic', id: 'claude-opus' },
  thinkingLevel: 'medium',
  steeringMode: 'all',
  followUpMode: 'all',
  autoCompactionEnabled: false
}
```

--------------------------------

### Get pi command with override

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Retrieves the executable name, optionally using an override value or environment variable.

```typescript
const cmd1 = getPiCommand()  
// Returns 'pi' on Unix, 'pi.cmd' on Windows

const cmd2 = getPiCommand('/usr/local/bin/pi')
// Returns '/usr/local/bin/pi'

const cmd3 = getPiCommand(process.env.PI_ACP_PI_COMMAND)
// Returns env var value if set, otherwise default
```

```typescript
const cmd = getPiCommand(process.env.PI_ACP_PI_COMMAND)
```

--------------------------------

### create(params: SessionCreateParams): Promise<PiAcpSession>

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Creates a new session with a freshly spawned pi subprocess.

```APIDOC
## Method: create

### Description
Creates a new session with a freshly spawned pi subprocess.

### Parameters
- **params.cwd** (string) - Required - Working directory (absolute path)
- **params.mcpServers** (McpServer[]) - Optional - MCP servers to store
- **params.conn** (AgentSideConnection) - Required - ACP connection for sending updates
- **params.fileCommands** (FileSlashCommand[]) - Optional - Pre-loaded slash command definitions from files
- **params.piCommand** (string) - Optional - Override pi executable name/path

### Returns
- **PiAcpSession** - The created session instance

### Throws
- **RequestError.internalError** - If pi subprocess fails to spawn
```

--------------------------------

### Define a File-Based Prompt

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Create markdown files in the specified global or project directories to define custom agent prompts.

```markdown
# Refactor Code

Carefully refactor the provided code:
- Improve readability
- Maintain behavior
- Add type safety where applicable
```

--------------------------------

### Consume Prelude Lines

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Retrieves and clears human-readable startup messages emitted before RPC communication begins.

```typescript
const lines = proc.consumePreludeLines()
// ['pi v0.80.4', 'Context: AGENTS.md', 'Skills: skill1, skill2']
```

--------------------------------

### Verify Command Selection on Windows and Unix

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Use these scripts to test command resolution and shell requirements across different operating systems.

```bash
# On Windows
node -e "
const { getPiCommand, shouldUseShellForPiCommand } = require('./dist/pi-rpc/command.js');
console.log('Default:', getPiCommand());
console.log('With override:', getPiCommand('C:\\custom\\pi.cmd'));
console.log('Shell needed:', shouldUseShellForPiCommand(getPiCommand()));
"
```

```bash
# On Unix
node -e "
const { getPiCommand, shouldUseShellForPiCommand } = require('./dist/pi-rpc/command.js');
console.log('Default:', getPiCommand());
console.log('With override:', getPiCommand('/usr/local/bin/pi'));
console.log('Shell needed:', shouldUseShellForPiCommand(getPiCommand()));
"
```

--------------------------------

### Tool Call Update Event Structure

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Example of a tool call update event emitted when a tool execution completes.

```typescript
{
  sessionUpdate: 'tool_call',
  toolCallId: 'tool-123',
  title: 'edit src/main.ts',
  kind: 'edit',
  status: 'completed',
  content: [{ type: 'diff', oldText: '...', newText: '...' }]
}
```

--------------------------------

### Configure Zed Agent Server

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Set up the pi-acp agent server within the Zed editor configuration using either the registry or npx.

```json
{
  "agent_servers": {
    "pi-acp": {
      "type": "registry"
    }
  }
}
```

```json
{
  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "pi-acp"],
      "env": {}
    }
  }
}
```

--------------------------------

### Execute pi-acp with Default Behavior

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Standard execution commands for macOS/Linux and Windows environments.

```bash
pi-acp
# Uses: spawn('pi', ['--mode', 'rpc'], { shell: false })
```

```batch
pi-acp
# Uses: spawn('pi.cmd', ['--mode', 'rpc'], { shell: true })
```

--------------------------------

### Create a New Session

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Spawn a new pi subprocess and register it as a session. Requires an absolute path for the working directory and an active connection.

```typescript
const session = await manager.create({
  cwd: '/home/user/project',
  conn,
  fileCommands: []
})
```

--------------------------------

### SessionStore Constructor

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session-store.md

Initializes a new instance of the SessionStore to manage session metadata mapping.

```APIDOC
## constructor(path?: string)

### Description
Initializes the SessionStore. If no path is provided, it defaults to `~/.pi/pi-acp/session-map.json`.

### Parameters
#### Path Parameters
- **path** (string) - Optional - Path to the session map file.
```

--------------------------------

### Define Slash Command Paths

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Specifies the directory locations for global and project-scoped markdown prompt files.

```text
~/.pi/agent/prompts/**/*.md
```

```text
<cwd>/.pi/prompts/**/*.md
```

--------------------------------

### newSession

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Creates a new ACP session with a fresh pi subprocess, fetching models and configuration.

```APIDOC
## newSession

### Description
Creates a new ACP session with a fresh pi subprocess. Spawns `pi --mode rpc` and fetches available models, configuration, and startup information.

### Parameters
- **params.cwd** (string) - Required - Working directory (must be absolute path)
- **params.mcpServers** (McpServer[]) - Optional - MCP servers (accepted but not wired to pi in MVP)

### Returns
- **sessionId** (string) - Unique session identifier
- **configOptions** (object) - Available session configuration options
- **models** (object) - Available AI models and current selection
- **modes** (array) - Available thinking modes
- **_meta.piAcp.startupInfo** (string) - Optional human-readable startup prelude

### Example
```typescript
const session = await agent.newSession({
  cwd: '/home/user/project'
})
```
```

--------------------------------

### getCommands()

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Retrieves available slash commands and skills from pi.

```APIDOC
## getCommands()

### Description
Retrieves available slash commands and skills from pi.

### Returns
- **Promise<unknown>** - An object containing a `categories` array with commands and skills.
```

--------------------------------

### toAvailableCommandsFromPiGetCommands

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Converts a raw Pi RPC response into a structured list of ACP available commands, with options to include skill or extension commands.

```APIDOC
## toAvailableCommandsFromPiGetCommands(piResponse, opts)

### Description
Converts pi's `get_commands` response into ACP available commands. It extracts prompts/commands, filters them based on provided options, and formats them as ACP AvailableCommand objects.

### Parameters
- **piResponse** (unknown) - Required - Raw pi RPC response
- **opts.enableSkillCommands** (boolean) - Optional - Include `/skill:` commands
- **opts.includeExtensionCommands** (boolean) - Optional - Include pi extension commands

### Returns
- **commands** (Array<AvailableCommand>) - The formatted list of available commands.
```

--------------------------------

### Instantiate PiAcpAgent

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Initialize the agent using an AgentSideConnection.

```typescript
const agent = new PiAcpAgent(conn)
```

--------------------------------

### session/list

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Lists all available sessions.

```APIDOC
## session/list

### Description
Retrieves a list of existing sessions.
```

--------------------------------

### Inspect session files

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Commands to list sessions and view session history or maps using jq.

```bash
# List sessions
ls ~/.pi/agent/sessions/

# View session history (NDJSON)
cat ~/.pi/agent/sessions/abc-123.jsonl | jq '.'

# View session map
cat ~/.pi/pi-acp/session-map.json | jq '.'
```

--------------------------------

### Spawn a PiRpcProcess instance

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Initializes a new pi subprocess in RPC mode using the specified working directory.

```typescript
const proc = await PiRpcProcess.spawn({
  cwd: '/home/user/project'
})
```

--------------------------------

### Initialize Endpoint Request and Response

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Request and response schemas for the initialize handshake and capability negotiation.

```typescript
{
  protocolVersion: 1,
  clientCapabilities?: {
    _meta?: { 'terminal-auth'?: boolean }
  }
}
```

```typescript
{
  protocolVersion: 1,
  agentInfo: {
    name: 'pi-acp',
    title: 'pi ACP adapter',
    version: '0.0.33'
  },
  authMethods: [
    { type: 'terminal', name?: 'Terminal Auth' }
  ],
  agentCapabilities: {
    loadSession: true,
    mcpCapabilities: { http: false, sse: false },
    promptCapabilities: {
      image: true,
      audio: false,
      embeddedContext: false  // true if PI_ACP_ENABLE_EMBEDDED_CONTEXT=true
    },
    sessionCapabilities: {
      list: {},
      delete: {}
    }
  }
}
```

--------------------------------

### Handle Streaming Updates

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/README.md

Demonstrates how to listen for session updates and handle message chunks or tool calls.

```typescript
// Pseudo-code (client-side, not adapter-side)
connection.on('session/update', (params) => {
  const { sessionId, update } = params
  
  if (update.sessionUpdate === 'agent_message_chunk') {
    console.log('Agent:', update.content.text)
  }
  
  if (update.sessionUpdate === 'tool_call') {
    console.log('Tool:', update.title, update.kind)
  }
  
  if (update.sessionUpdate === 'tool_call_update') {
    console.log('Tool status:', update.status)
  }
})
```

--------------------------------

### session/load

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Resumes a previous session.

```APIDOC
## session/load

### Description
Loads and resumes a previously created session.
```

--------------------------------

### listPiSessions

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Discovers all pi sessions stored on disk.

```APIDOC
## listPiSessions()

### Description
Scans the local disk for pi sessions, extracts metadata, and returns a list of complete sessions sorted by update time.

### Returns
- **Array<{ sessionId: string; cwd: string; title: string; updatedAt: string }>** - A list of session objects, sorted by updatedAt (newest first).
```

--------------------------------

### session/prompt

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Sends a user prompt to the session and streams assistant responses.

```APIDOC
## session/prompt

### Description
Sends a user prompt to the session and streams assistant responses via session/update notifications. Supports text, image, and resource content types, as well as built-in slash commands.

### Method
session/prompt

### Request Body
- **sessionId** (string) - Required - The ID of the active session.
- **prompt** (object) - Required - The prompt content containing text, images, or resources.

### Response
#### Success Response
- **stopReason** ('end_turn' | 'cancelled' | 'error') - The reason for the turn completion.

### Streaming Updates
Updates are sent via `session/update` notifications, including:
- **agent_message_chunk**: Text content from the agent.
- **tool_call**: Notifications for tool execution (e.g., edit, execute).
- **tool_call_update**: Status updates for ongoing tool executions.
```

--------------------------------

### getAvailableModels()

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Queries the pi process for available models configured in the environment.

```APIDOC
## getAvailableModels()

### Description
Queries pi for available models configured in the user's environment.

### Returns
- **Promise<unknown>** - An object containing a `models` array, where each entry includes `provider`, `id`, and `name`.
```

--------------------------------

### defaultPiCommand()

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Returns the default pi executable name based on the current platform.

```APIDOC
## defaultPiCommand()

### Description
Returns the default pi executable name based on the current platform.

### Returns
- **string** - 'pi.cmd' on Windows, 'pi' on Unix/Linux/macOS.
```

--------------------------------

### Configure pi-acp via Registry

Source: https://github.com/svkozak/pi-acp/blob/main/README.md

Configuration for clients supporting the ACP registry.

```json
  "agent_servers": {
    "pi-acp": {
      "type": "registry",
    },
  }
```

--------------------------------

### Configure Zed with ACP Registry

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Recommended method for automatic discovery and updates of the pi-acp agent.

```json
{
  "agent_servers": {
    "pi-acp": {
      "type": "registry"
    }
  }
}
```

--------------------------------

### PiRpcProcess.spawn

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Spawns a new pi subprocess in RPC mode and establishes communication channels.

```APIDOC
## static async spawn(params: SpawnParams): Promise<PiRpcProcess>

### Description
Spawns a new pi subprocess in RPC mode and establishes communication. Runs `pi --mode rpc --no-themes [--session <path>]`.

### Parameters
- **params.cwd** (string) - Required - Working directory for pi subprocess
- **params.piCommand** (string) - Optional - Override pi executable
- **params.sessionPath** (string) - Optional - Path to session file to resume

### Returns
- **Promise<PiRpcProcess>** - A promise that resolves to the spawned process instance.

### Throws
- **PiRpcSpawnError** - Thrown if the process fails to spawn (e.g., ENOENT, EACCES).
```

--------------------------------

### PiAcpAgent Constructor

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Initializes a new instance of the PiAcpAgent with an ACP connection.

```APIDOC
## Constructor

### Description
Initializes the PiAcpAgent with the required ACP connection.

### Parameters
- **conn** (AgentSideConnection) - Required - The ACP connection to send updates and receive requests from the client.
- **_config** (unknown) - Optional - Unused configuration parameter.

### Example
```typescript
const agent = new PiAcpAgent(conn)
```
```

--------------------------------

### session/prompt

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Sends a prompt to the active session.

```APIDOC
## session/prompt

### Description
Sends a prompt to the adapter. The adapter responds immediately with a stop reason and streams updates via session/update notifications.

### Method
JSON-RPC Request

### Response
- **stopReason** (string) - The reason for the immediate response.
```

--------------------------------

### loadSlashCommands(cwd: string)

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

Discovers and loads all available slash commands from markdown files in the specified project working directory and global user directories.

```APIDOC
## loadSlashCommands(cwd: string)

### Description
Discovers all slash commands available from markdown files in the project and user directories. It searches in `<cwd>/.pi/prompts/**/*.md` and `~/.pi/agent/prompts/**/*.md`.

### Parameters
- **cwd** (string) - Required - Project working directory

### Returns
- **FileSlashCommand[]** - An array of objects containing `name`, `description`, and `content` for each command.

### Example
```typescript
const commands = loadSlashCommands('/home/user/project');
```
```

--------------------------------

### Initialize a new ACP session

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Spawns a new pi subprocess and retrieves session configuration. Requires an absolute path for the working directory.

```typescript
const session = await agent.newSession({
  cwd: '/home/user/project'
})
// { sessionId: 'abc-123', configOptions: [...], models: {...}, ... }
```

--------------------------------

### getPiCommand(override?)

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/command.md

Returns the pi executable name, allowing for environment-based override.

```APIDOC
## getPiCommand(override?)

### Description
Returns the pi executable name, allowing for environment-based override. If an override is provided, it is returned; otherwise, the default platform-specific command is returned.

### Parameters
- **override** (string) - Optional - Optional override value (typically from PI_ACP_PI_COMMAND env var).

### Returns
- **string** - The resolved pi executable name.
```

--------------------------------

### getQuietStartup

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Checks if quietStartup is enabled in the project settings.

```APIDOC
## getQuietStartup

### Description
Checks if `quietStartup: true` is set in pi settings by reading the configuration file in the provided working directory or the default agent path.

### Signature
`getQuietStartup(cwd: string): boolean`

### Parameters
- **cwd** (string) - Required - Session working directory

### Returns
- **boolean** - Returns true if quietStartup is set, false otherwise.
```

--------------------------------

### PiRpcProcess.prompt

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Sends a user prompt to the pi subprocess and waits for acknowledgment.

```APIDOC
## async prompt(message: string, images: unknown[] = []): Promise<void>

### Description
Sends a user prompt to pi and waits for acknowledgment. Actual response events are handled via `onEvent()` listener.

### Parameters
- **message** (string) - Required - User message text
- **images** (unknown[]) - Optional - Optional image payloads (ACP content blocks)

### Returns
- **Promise<void>** - Resolves when pi acknowledges the request.

### Throws
- **Error** - Thrown if the prompt fails.
```

--------------------------------

### getState()

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Queries the pi process for the current session state.

```APIDOC
## getState()

### Description
Queries pi for current session state including model, thinking level, session file path, and message count.

### Returns
- **Promise<unknown>** - An object containing session details such as `sessionId`, `sessionFile`, `messageCount`, `model`, `thinkingLevel`, `steeringMode`, `followUpMode`, and `autoCompactionEnabled`.
```

--------------------------------

### bashTerminalExitMeta

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Generates metadata for bash command completion.

```APIDOC
## bashTerminalExitMeta(toolCallId: string, exitCode: number)

### Description
Generates metadata for the final tool call update indicating command completion status.

### Parameters
- **toolCallId** (string) - Required - Unique identifier for the tool call.
- **exitCode** (number) - Required - The process exit code.

### Returns
- **Record<string, unknown>** - Metadata object.
```

--------------------------------

### Define a custom slash command file path

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/slash-commands.md

The file path for a custom slash command within the project directory.

```text
<project>/.pi/prompts/code-review.md
```

--------------------------------

### isSemver(v: string): boolean

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Checks if a provided string adheres to the semantic versioning format.

```APIDOC
## isSemver(v: string)

### Description
Checks if a string matches semantic versioning format.

### Parameters
- **v** (string) - Required - Version string

### Returns
- **boolean** - Returns true if the string is a valid semantic version, false otherwise.
```

--------------------------------

### session/list

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/acp-protocol-endpoints.md

Lists previously created sessions available for resumption with support for pagination and filtering by working directory.

```APIDOC
## session/list

### Description
Lists previously created sessions available for resumption. If no working directory is provided, it defaults to the most recently used one.

### Method
session/list

### Parameters
- **cwd** (string) - Optional - Filter by working directory.
- **cursor** (string) - Optional - Pagination cursor (opaque numeric offset).

### Response
- **sessions** (Array) - List of session objects containing sessionId, cwd, title, and updatedAt.
- **nextCursor** (string | null) - Pagination cursor for the next page.
```

--------------------------------

### getOrCreate

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Returns an existing session or creates a new wrapper around an existing pi subprocess.

```APIDOC
## getOrCreate(sessionId: string, params: SessionCreateParams & { proc: PiRpcProcess }): PiAcpSession

### Description
Returns an existing session or creates a new wrapper around an existing pi subprocess.

### Parameters
- **sessionId** (string) - Required - Session ID
- **params** (SessionCreateParams & { proc: PiRpcProcess }) - Required - Creation params plus pre-instantiated pi process

### Returns
- **PiAcpSession** - The session object
```

--------------------------------

### listSessions

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Lists previously created pi sessions stored on disk with support for filtering and pagination.

```APIDOC
## Method: listSessions

### Description
Lists previously created pi sessions stored on disk. Filters by `cwd` if provided, otherwise defaults to the most recently used cwd. Supports cursor-based pagination (50 items per page).

### Signature
`async listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse>`

### Parameters
- **params.cwd** (string) - Optional - Filter sessions by working directory
- **params.cursor** (string) - Optional - Pagination cursor (numeric offset as string)

### Returns
- **sessions** (Array<SessionInfo>) - List of session objects
- **nextCursor** (string|null) - Cursor for next page

### Example
```typescript
const result = await agent.listSessions({ cwd: '/home/user/project' })
// { sessions: [{sessionId: 'abc-123', cwd: '...', ...}], nextCursor: null }
```
```

--------------------------------

### getAuthMethods

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/helpers.md

Retrieves the list of available authentication methods for the initialize response.

```APIDOC
## getAuthMethods

### Description
Builds the list of available authentication methods for the initialize response.

### Signature
`getAuthMethods(opts?: { supportsTerminalAuthMeta?: boolean }): AuthMethod[]`

### Parameters
- **opts.supportsTerminalAuthMeta** (boolean) - Optional - If client supports terminal auth metadata

### Returns
- **AuthMethod[]** - List of available authentication methods
```

--------------------------------

### Configure PI_ACP_PI_COMMAND environment variable

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

Set the path to the pi executable when it is not on the system PATH.

```bash
PI_ACP_PI_COMMAND=/usr/local/bin/pi node dist/index.js
```

--------------------------------

### Switch Session Method

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Defines the signature for switching the subprocess to a different session file.

```typescript
async switchSession(sessionPath: string): Promise<void>
```

--------------------------------

### compact

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/pi-rpc-process.md

Manually compacts the session context to reduce token usage.

```APIDOC
## compact

### Description
Manually compacts the session context to reduce token usage.

### Signature
`async compact(customInstructions?: string): Promise<unknown>`

### Parameters
- **customInstructions** (string) - Optional - Optional custom instructions for the compaction

### Returns
- **Promise<unknown>** - Object with `tokensBefore`, `tokensAfter`, `summary`

### Example
```typescript
const result = await proc.compact('Focus on keeping error handling logic')
// { tokensBefore: 1500, summary: 'Session compacted...' }
```
```

--------------------------------

### InitializeRequest and InitializeResponse Interfaces

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/types.md

Defines the handshake structures for protocol versioning and agent capability negotiation.

```typescript
// From @agentclientprotocol/sdk
interface InitializeRequest {
  protocolVersion: number
  clientCapabilities?: { _meta?: Record<string, unknown> }
}

interface InitializeResponse {
  protocolVersion: number
  agentInfo: { name: string; title: string; version: string }
  authMethods?: AuthMethod[]
  agentCapabilities: {
    loadSession?: boolean
    mcpCapabilities?: { http: boolean; sse: boolean }
    promptCapabilities?: { image?: boolean; audio?: boolean; embeddedContext?: boolean }
    sessionCapabilities?: { list?: {}; delete?: {} }
  }
}
```

--------------------------------

### Initialize ACP Agent

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Handle the initialize request to establish protocol version and agent capabilities.

```typescript
const response = await agent.initialize({
  protocolVersion: 1,
  clientCapabilities: { ... }
})
// { protocolVersion: 1, agentInfo: { name: 'pi-acp', ... }, ... }
```

--------------------------------

### Configure API Key

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/errors.md

Sets the environment variable for the Anthropic API key to enable model access.

```bash
export ANTHROPIC_API_KEY=sk-...
pi-acp  # Should now have models available
```

--------------------------------

### Session Map Path

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/configuration.md

The location of the JSON file used for quick session lookups.

```text
~/.pi/pi-acp/session-map.json
```

--------------------------------

### prompt

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/agent.md

Sends a user prompt to the session and streams assistant responses, handling built-in slash commands.

```APIDOC
## prompt

### Description
Sends a user prompt to the session and streams assistant responses back as ACP `agent_message_chunk` and `tool_call` events. Also handles built-in slash commands.

### Parameters
- **params.sessionId** (string) - Required - ID of target session
- **params.prompt** (Prompt) - Required - User message with optional images and embedded resources

### Returns
- **stopReason** ('end_turn' | 'cancelled' | 'error') - The reason for the interaction stopping

### Built-in Slash Commands
- `/compact [instructions]`
- `/autocompact on|off|toggle`
- `/session`
- `/name <name>`
- `/steering [all | one-at-a-time]`
- `/follow-up [all | one-at-a-time]`
- `/export`
- `/changelog`
- `/skill:skill-name`

### Example
```typescript
const result = await agent.prompt({
  sessionId: 'abc-123',
  prompt: { content: [{ type: 'text', text: 'Write a function' }] }
})
```
```

--------------------------------

### prompt(message: string, images: unknown[])

Source: https://github.com/svkozak/pi-acp/blob/main/_autodocs/api-reference/session.md

Sends a user prompt to pi and streams back assistant response via ACP session updates. Queues additional prompts if one is already in-flight.

```APIDOC
## prompt(message: string, images: unknown[])

### Description
Sends a user prompt to pi and streams back assistant response via ACP session updates. Queues additional prompts if one is already in-flight.

### Parameters
- **message** (string) - Required - User message text
- **images** (unknown[]) - Optional - Array of image objects (ACP content blocks)

### Returns
- **StopReason** - 'end_turn', 'cancelled', or 'error'

### Example
```typescript
const reason = await session.prompt('Fix the bug in main.ts', [])
```
```
Tokens:
Raw