### Local Development Setup Commands

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

These bash commands are used to clone the repository, install dependencies, and run development tasks for the opencode-pty project locally.

```bash
git clone https://github.com/shekohex/opencode-pty.git
cd opencode-pty
bun ci          # install packages from bun.lock
bun lint        # Runs Biome linting checks
bun format      # Runs Biome formatting checks
bun typecheck   # Runs TypeScript type checking
bun build:dev   # Build the React app for development
bun unittest    # Runs the unit tests
bun test:e2e    # Runs the e2e tests
```

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

### Spawn a Dev Server

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/spawn.txt

Starts a long-running development server process in the background. No timeout is set by default.

```javascript
pty_spawn({
  command: "npm",
  args: ["run", "dev"],
  title: "Dev Server"
});
```

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

### Start a Development Server

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Initiates the development server using npm run dev. This command returns a PTY ID for further interaction.

```bash
pty_spawn: command="npm", args=["run", "dev"], title="Dev Server"
```

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

### Start a Timed PTY Session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Starts a PTY session with a specified timeout in seconds. The command returns a PTY ID.

```bash
pty_spawn: command="npm", args=["run", "dev"], title="Dev Server", timeoutSeconds=600
```

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

### Spawn a Python REPL

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/spawn.txt

Starts an interactive Python REPL session in the background. Suitable for interactive coding or scripting.

```javascript
pty_spawn({
  command: "python3",
  title: "Python REPL"
});
```

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

### Spawn a Timed Dev Server

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/spawn.txt

Starts a development server with an explicit timeout. Use this when a user specifically requests a time limit for a long-running process.

```javascript
pty_spawn({
  command: "npm",
  args: ["run", "dev"],
  title: "Dev Server",
  timeoutSeconds: 600
});
```

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

### Configure opencode-pty Plugin

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Add the opencode-pty plugin to your OpenCode configuration file. OpenCode will automatically install it on the next run.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-pty"]
}
```

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

### Get session output buffer (raw data)

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Retrieves the raw session output buffer data.

```APIDOC
## GET /api/sessions/:id/buffer/raw

### Description
Get session output buffer (raw data).

### Method
GET

### Endpoint
/api/sessions/:id/buffer/raw
```

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

### Run PTY Session with Exit Notification

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Starts a PTY session and notifies the AI agent upon process exit. This is suitable for long-running tasks like builds.

```bash
pty_spawn: command="npm", args=["run", "build"], title="Build", notifyOnExit=true
```

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

### Get session details

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Retrieves detailed information about a specific PTY session identified by its ID.

```APIDOC
## GET /api/sessions/:id

### Description
Get session details.

### Method
GET

### Endpoint
/api/sessions/:id
```

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

### Get session output buffer (plain text)

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Retrieves the session output buffer as plain text, along with its byte length.

```APIDOC
## GET /api/sessions/:id/buffer/plain

### Description
Get session output buffer (returns `{ plain: string, byteLength: number }`).

### Method
GET

### Endpoint
/api/sessions/:id/buffer/plain

### Response
#### Success Response (200)
- **plain** (string) - The session output in plain text.
- **byteLength** (number) - The byte length of the output buffer.

#### Response Example
{
  "example": "{\"plain\": \"Session output...\", \"byteLength\": 123}"
}
```

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

### List All PTY Sessions

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `pty_list` tool to get a list of all active PTY sessions. The output includes their status, process ID (PID), and line count.

```javascript
pty_list()
```

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

### PTY Process Exit Notification XML

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Example XML structure received by the AI agent when a PTY process exits, providing details like ID, title, exit code, and output summary.

```xml
<pty_exited>
ID: pty_a1b2c3d4
Title: Build
Exit Code: 0
Output Lines: 42
Last Line: Build completed successfully.
</pty_exited>
```

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

### Spawn Build with Notification and Timeout

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/spawn.txt

Executes a build process with a specified timeout and enables exit notifications. Useful for commands that are expected to finish within a certain time.

```javascript
pty_spawn({
  command: "npm",
  args: ["run", "build"],
  title: "Build",
  notifyOnExit: true,
  timeoutSeconds: 900
});
```

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

### Create a new PTY session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Initiates a new pseudo-terminal session with a specified command and arguments. Supports optional description and timeout.

```APIDOC
## POST /api/sessions

### Description
Create a new PTY session.

### Method
POST

### Endpoint
/api/sessions

### Request Body
- **command** (string) - Required - The command to execute.
- **args** (array of strings) - Optional - Arguments for the command.
- **description** (string) - Optional - A description for the session.
- **timeoutSeconds** (number) - Optional - The session timeout in seconds.

### Request Example
{
  "example": "{\"command\": \"bash\", \"args\": [\"-c\", \"echo hello && sleep 10\"], \"description\": \"Test session\", \"timeoutSeconds\": 5}"
}
```

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

### Loading Local Plugin Checkout

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

This JSON configuration snippet shows how to load a local checkout of the opencode-pty plugin in OpenCode by specifying the absolute path to the plugin's entry point.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["file:///absolute/path/to/opencode-pty/index.ts"]
}
```

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

### Show PTY Web Server URL

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `/pty-show-server-url` slash command to display the URL of the currently running PTY web server instance.

```bash
/pty-show-server-url
```

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

### Create a PTY Session via REST API

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use this cURL command to create a new PTY session with a specified command, arguments, description, and timeout.

```bash
curl -X POST http://localhost:[PORT]/api/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "command": "bash",
    "args": ["-c", "echo hello && sleep 10"],
    "description": "Test session",
    "timeoutSeconds": 5
  }'
```

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

### Spawn Tests in Watch Mode

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/spawn.txt

Initiates a test suite that runs in watch mode, automatically re-running tests on file changes. This is a long-running process.

```javascript
pty_spawn({
  command: "npm",
  args: ["test", "--", "--watch"]
});
```

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

### /pty-show-server-url

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Displays the URL of the running PTY web server instance.

```APIDOC
## /pty-show-server-url

### Description
Shows the URL for the PTY web server.

### Command
`/pty-show-server-url`

### Usage
This slash command, when executed in OpenCode chat, will output the URL where the PTY web UI can be accessed.
```

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

### Default Bash Permissions

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

This JSON configuration sets default permissions for the bash tool within OpenCode. It allows 'npm *' commands but denies 'git push' and 'terraform *'.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "npm *": "allow",
      "git push": "deny",
      "terraform *": "deny"
    }
  }
}
```

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

### pty_spawn

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Creates a new pseudo-terminal (PTY) session. This allows the agent to run commands in the background or interactively.

```APIDOC
## pty_spawn

### Description
Creates a new PTY session to run a command.

### Method
`pty_spawn`

### Parameters
- **command** (string) - Required - The command to execute.
- **args** (array of strings) - Optional - Arguments for the command.
- **workdir** (string) - Optional - The working directory for the command.
- **env** (object) - Optional - Environment variables for the command.
- **title** (string) - Optional - A title for the PTY session.
- **notifyOnExit** (boolean) - Optional - Whether to notify when the process exits.
- **timeoutSeconds** (number) - Optional - Timeout for session creation.
```

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

### Open PTY Web UI

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `/pty-open-background-spy` slash command in OpenCode chat to open the PTY web server interface in your browser. This provides a visual way to monitor and interact with PTY sessions.

```bash
/pty-open-background-spy
```

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

### Force Reinstall opencode-pty Plugin

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

To force a clean reinstallation of the opencode-pty plugin, clear the plugin's cached files and restart OpenCode.

```bash
rm -rf ~/.cache/opencode/node_modules/opencode-pty
opencode
```

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

### Spawn End-to-End Tests with Timeout

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/spawn.txt

Launches end-to-end tests with a timeout and exit notifications. This is suitable for test suites that have a defined maximum execution time.

```javascript
pty_spawn({
  command: "npm",
  args: ["run", "test:e2e"],
  title: "E2E Tests",
  notifyOnExit: true,
  timeoutSeconds: 1800
});
```

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

### Allow Specific Commands for PTY

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

This JSON configuration explicitly allows several npm, cargo, and python commands for use with the PTY plugin. This is useful for fine-grained control over allowed operations.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "npm run dev": "allow",
      "npm run build": "allow",
      "npm test *": "allow",
      "cargo *": "allow",
      "python *": "allow"
    }
  }
}
```

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

### Spawn a New PTY Session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `pty_spawn` tool to create a new pseudo-terminal session. This tool supports specifying the command, arguments, working directory, environment variables, title, and exit notifications.

```javascript
pty_spawn(command, args, workdir, env, title, notifyOnExit, timeoutSeconds)
```

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

### Real-time PTY Session Updates via WebSocket

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Connect to the WebSocket endpoint to receive real-time updates on session output and session lists. Replace [PORT] with the actual server port.

```javascript
const ws = new WebSocket('ws://localhost:[PORT]/ws')

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  if (data.type === 'raw_data') {
    console.log('New output:', data.rawData)
  } else if (data.type === 'session_list') {
    console.log('Session list:', data.sessions)
  }
}
```

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

### Send input to a session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Sends data as input to a running PTY session identified by its ID.

```APIDOC
## POST /api/sessions/:id/input

### Description
Send input to a session.

### Method
POST

### Endpoint
/api/sessions/:id/input

### Request Body
- **data** (string) - Required - The input data to send.

### Request Example
{
  "example": "{\"data\": \"\x03\"}"
}
```

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

### Send a command to PTY

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/write.txt

Use this to send a command string followed by a newline character to an active PTY session.

```bash
data="ls -la\n"
```

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

### /pty-open-background-spy

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Opens the PTY web server interface in the browser, allowing for visual monitoring and interaction with PTY sessions.

```APIDOC
## /pty-open-background-spy

### Description
Opens the PTY web UI in the browser.

### Command
`/pty-open-background-spy`

### Usage
This slash command, when executed in OpenCode chat, will start the PTY web server and open the UI in your default browser.
```

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

### Answer a prompt in PTY

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/write.txt

Provide an affirmative response (e.g., 'yes') followed by a newline to answer a prompt in an interactive program within the PTY session.

```bash
data="yes\n"
```

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

### pty_write

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Sends input to an existing PTY session. This can include text and escape sequences.

```APIDOC
## pty_write

### Description
Sends input to a PTY session.

### Method
`pty_write`

### Parameters
- **text** (string) - Required - The text or escape sequence to send (e.g., `\x03` for Ctrl+C).
- **sessionId** (string) - Required - The ID of the PTY session to write to.
```

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

### Read Output from a PTY Session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `pty_read` tool to retrieve output from a PTY session's buffer. It supports pagination with offset and limit, and optional regex filtering similar to `grep`.

```javascript
pty_read(offset, limit, regexFilter)
```

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

### Server health check

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Checks the health status of the server and retrieves associated metrics.

```APIDOC
## GET /health

### Description
Server health check with metrics.

### Method
GET

### Endpoint
/health
```

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

### pty_list

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Lists all active PTY sessions, including their status, PID, and line count.

```APIDOC
## pty_list

### Description
Lists all currently active PTY sessions.

### Method
`pty_list`

### Parameters
None
```

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

### Send Input to a PTY Session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `pty_write` tool to send input to an active PTY session. This includes regular text and escape sequences for special keys like Ctrl+C.

```javascript
pty_write(text, escapeSequences)
```

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

### Kill and cleanup a session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Terminates a PTY session identified by its ID and performs cleanup operations.

```APIDOC
## DELETE /api/sessions/:id/cleanup

### Description
Kill and cleanup a session.

### Method
DELETE

### Endpoint
/api/sessions/:id/cleanup
```

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

### List all PTY sessions

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Retrieves a list of all active PTY sessions managed by the server.

```APIDOC
## GET /api/sessions

### Description
List all PTY sessions.

### Method
GET

### Endpoint
/api/sessions
```

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

### Kill and Cleanup PTY Session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Terminates a PTY session and frees its associated buffer. Set cleanup to true for complete removal.

```bash
pty_kill: id="pty_a1b2c3d4", cleanup=true
```

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

### Read PTY Session Output

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Retrieves the last specified number of lines from a PTY session's output buffer. Useful for checking server output.

```bash
pty_read: id="pty_a1b2c3d4", limit=50
```

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

### pty_read

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Reads the output buffer of a PTY session with support for pagination and regex filtering.

```APIDOC
## pty_read

### Description
Reads output from a PTY session's buffer.

### Method
`pty_read`

### Parameters
- **sessionId** (string) - Required - The ID of the PTY session to read from.
- **offset** (number) - Optional - The starting offset for reading.
- **limit** (number) - Optional - The maximum number of lines to read.
- **filterRegex** (string) - Optional - A regex pattern to filter the output.
```

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

### pty_kill

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Terminates a PTY session. Optionally, the output buffer can also be cleaned up.

```APIDOC
## pty_kill

### Description
Terminates a PTY session.

### Method
`pty_kill`

### Parameters
- **sessionId** (string) - Required - The ID of the PTY session to kill.
- **cleanupBuffer** (boolean) - Optional - Whether to also clear the output buffer.
```

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

### Kill a session (without cleanup)

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Terminates a PTY session identified by its ID without performing any cleanup operations.

```APIDOC
## DELETE /api/sessions/:id

### Description
Kill a session (without cleanup).

### Method
DELETE

### Endpoint
/api/sessions/:id
```

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

### Terminate a PTY Session

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Use the `pty_kill` tool to terminate a PTY session. You can optionally choose to clean up the session's output buffer.

```javascript
pty_kill(cleanupBuffer)
```

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

### Filter PTY Session Output for Errors

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Reads PTY session output, filtering lines that match a given pattern (case-insensitive). Useful for identifying errors.

```bash
pty_read: id="pty_a1b2c3d4", pattern="error|ERROR", ignoreCase=true
```

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

### Interrupt a process in PTY

Source: https://github.com/shekohex/opencode-pty/blob/main/src/plugin/pty/tools/write.txt

Send the Ctrl+C interrupt signal (\x03) to a running process within the PTY session.

```bash
data="\x03"
```

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

### Clear all sessions

Source: https://github.com/shekohex/opencode-pty/blob/main/README.md

Removes all active PTY sessions from the server.

```APIDOC
## DELETE /api/sessions

### Description
Clear all sessions.

### Method
DELETE

### Endpoint
/api/sessions
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.