Skip to main content

OpenCode PTY

tip

435 GitHub stars — Interactive terminal management for AI agents. Run background processes, send input, and filter output with regex.

Overview​

OpenCode PTY enables AI agents to manage pseudo-terminals (PTY). Unlike the standard bash tool which runs a single command and waits for output, PTY allows agents to start long-running interactive processes, send input to them over time, and read output with regex filtering. This is essential for dev servers, interactive debuggers, database shells, and any process that expects ongoing interaction.

When to Use​

ScenarioBenefit
Live dev serversStart a dev server and monitor its output during development
Interactive debuggersStep through code with pdb, lldb, or node inspect
Database shellsExecute multiple queries in a persistent psql session
CLI toolsInteract with tools that require user input sequences
Long-running processesMonitor build or test watchers that run continuously

How It Works​

  1. PTY creation — The agent starts a process in a pseudo-terminal.
  2. Output streaming — Output is captured continuously and made available to the agent.
  3. Input injection — The agent can send keystrokes or commands to the PTY at any time.
  4. Regex filtering — Output can be filtered to capture specific patterns or events.
  5. PTY cleanup — When the agent is done, the PTY is terminated.

Installation​

{
  "plugin": ["opencode-pty"]
}

Configuration​

Basic Setup​

{
  "plugin": ["opencode-pty"]
}

With Permission Controls​

{
  "permission": {
    "opencode-pty_start": "allow",
    "opencode-pty_send": "allow"
  }
}

Usage​

Start a PTY​

The agent can start a long-running process:

Start a development server and monitor for changes.

The agent creates a PTY, runs npm run dev, and streams output for analysis.

Send Input to a Running PTY​

Send a SIGUSR1 signal to the dev server to reload configuration.

The agent sends the appropriate keystrokes or signals through the PTY.

Filter Output​

Monitor the dev server output for "error" or "warning" patterns.

The agent applies regex filtering to the PTY output stream and reports matching lines.

Examples​

Development Workflow​

opencode-pty:
  start: ["npm", "run", "dev"]
  filter: ["error", "Warning:", "compiled"]

Database Session​

opencode-pty:
  start: ["psql", "-U", "admin", "-d", "myapp"]
  filter: ["ERROR:", "ERRORS:"]

Debugger Session​

opencode-pty:
  start: ["node", "inspect", "server.js"]
  filter: ["breakpoint", "exception", "debug>"]

After hitting a breakpoint, the agent can send: next, step, continue

Best Practices​

Use Regex Filtering Efficiently​

  • Narrow filters reduce context noise from irrelevant PTY output.
  • Filter for errors, warnings, and status changes rather than all output.

Clean Up Idle PTYs​

  • Always terminate PTYs when they are no longer needed.
  • Unmonitored PTYs can accumulate and consume system resources.

Permission Safety​

  • Restrict PTY creation to trusted agents.
  • PTY processes have access to the same environment as OpenCode.

GitHub​

  • Repo: shekohex/opencode-pty
  • npm: opencode-pty
  • Topics: pty, background-processes, interactive-shell, regex
  • Category: Shell / Runtime