Communitygithub.com

PTY-Agent

An AI-accessible skill for interacting with interactive CLI programs via subprocess or pseudo-terminal (PTY) for bidirectional communication, offering a CLI interface to manage sessions.

What is PTY-Agent?

PTY-Agent is a command-line interactive program interaction agent designed for AI use, enabling bidirectional communication with interactive CLI programs through subprocess or pseudo-terminal (PTY). It operates via a background daemon that accepts user commands and interacts with the corresponding CLI. The agent is ideal for scenarios where direct scripting is impractical, such as forced interactive sessions with tools like GDB, long-running servers, or complex build operations that require continuous input and output monitoring. It supports session management (start/stop/exec/send/read/list/kill), configurable triggers and timeouts, crash detection, and GUI window handling. PTY-Agent outputs structured JSON for programmatic use and can switch to natural language output. It is not recommended for non-interactive tasks, GUI/browser automation, or complex TUI programs where scripting suffices.

Works with~Claude Code~Codex CLI~Cursor
npx skills add ming-14/PTY-Agent

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

What does PTY-Agent do?

PTY-Agent is a command-line interactive program interaction agent that communicates bidirectionally with interactive CLI programs via subprocess or pseudo-terminal (PTY).

Principle: A daemon runs in the background, accepting user commands and operating on the corresponding CLI.

The program is located in app.py, run with: python app.py ...

When to Use

  • Forced to have continuous conversation with an interactive program, needing to send input and wait for specific output (prompt) before continuing, such as GDB, server, or large program compilation. But if scripting is possible, do not use PTY-Agent
  • Process may block or run for too long — need periodic status checks
  • Child process may crash — need real-time crash event detection
  • Required to simulate user operations for testing

When Not to Use

  • Non-interactive tasks
  • Tasks fully scriptable and debuggable
  • GUI interfaces, browsers, complex TUI programs

Command Quick Reference

CommandPurposeTypical OptionsExample
start/stopManually start/stop the daemon; starting the daemon via exec is possible and generally not needed manually
exec <new-session-id> <options>Execute a command to start a session-c "<command>"(req), -t "<regex>", --timeout <seconds>, --cwd <path>exec id_py -c "python -i" -t ">>>"
send <session-id> "<content>" [options]Send input to a running session-t "<regex>", --timeout <seconds>send id_py "print(1)" -t ">>>"
read <session-id> [options]Read session output--lines, --grepread myid --lines 10
listList all sessions
kill <session-id>Terminate a session
events <session-id> [options]View session events--last <N>, `--since <iso-datetimeHH:MM>`
closewin <session-id> <window-handle>Close a GUI window; <window-handle> supports decimal or 0x hexadecimal

Return Conditions for Command send

ModeConditionReturned Information
With triggerRegex matchedIncremental output
With idle-timeoutIdle timeoutIncremental output
With timeoutTimeout reachedIncremental output
NoneDefault timeout reachedIncremental output
GUI detection not disabledGUI window detected (subprocess may not be available)GUI window info + incremental output
Process crashedRelated events + incremental output
Program exitedIncremental output

Note: Efficiently utilize this program's conditional return functionality; update conditions (especially -t) promptly based on the corresponding program's output, and use different return conditions flexibly. It is not recommended to execute Sleep in the terminal, or repeatedly send followed by read.

exec Usage

python app.py exec <session-id> <options>

Options are mostly the same as send.

Special options:

  • -c "<command>"(req) The command to execute, required
  • --shell <shell> Supports cmd/powershell/pwsh/bash (default PowerShell, falls back to CMD automatically if environment does not support it); terminal can only be configured at exec startup
  • --pty Enable full pseudo-terminal (does not support shell syntax like |, &&)
    • --force-pty-mode Ignore shell operator detection when --pty is used
  • --cwd <path> Working directory for the child process, defaults to the caller (client) working directory if not specified; if this differs from the expected working directory, it is recommended to specify

send Usage

python app.py send <session-id> "<content>" [options]

Options:

  • -t/--trigger "<regex>" Match a regex
    • --newline — Check regex trigger condition only after a newline, used with -t
  • --timeout <seconds> Wait timeout (default 120s)
    • --idle-after-first-output Start detecting idleness only after first output, used with --idle-timeout
    • Note: Efficiently utilize this program's conditional return functionality; update conditions (especially -t) promptly based on the corresponding program's output, and use different return conditions flexibly. It is not recommended to execute Sleep in the terminal, or repeatedly send followed by read.
  • --idle-timeout <seconds> Output idle timeout, triggers when no output occurs within the specified time
  • --full Return all terminal data (large data, prefer --lines N)
  • --json-escaping JSON escape mode, JSON-escapes <content> (\\ \" \n \t \r \uXXX ...), recommended when sending multi-line content

A newline is automatically appended to the end of <content>.

No --input parameter.

Quotation Handling Rules (Command Line Layer)

  • cmd writes \" nested: -c "python -c \"print(1)\""
  • PowerShell/Pwsh outer single quotes, inner double quotes: -c 'python -c "print(1)"'

read Usage

python app.py read <session-id> [options]

Options:

  • --lines <N> Last N lines
  • --lines start:end Range of lines
  • --grep "<regex>" Regex filter
  • --offset <bytes> Incremental read
  • --full Return all terminal data (large data, prefer --lines N)

events Complete Usage

python app.py events <session-id> [options]

Options:

  • --last N
  • --since <iso-datetime|HH:MM>
  • --until <iso-datetime|HH:MM>

Global/Common Options

  • --keep-ansi Preserve control codes
  • --color Enable terminal color output
  • --output-by-natural-language Natural language output
  • --encoding <encoding> Terminal encoding, set to utf-8/gbk/gb2312/gb18030/big5 for garbled characters
  • --no-debug Disable debug output in responses (process tree/GUI windows/events)
  • --show-config [KEY] View current call configuration
  • --default <KEY> <VALUE> Temporarily override default configuration (available keys: output-by-natural-language/timeout/newline/keep-ansi/encoding/debug, <VALUE> is the configuration value or on/off)

Output Format

  1. JSON mode (default) — stdout outputs JSON only, one JSON object per line. All non-command responses (daemon start/stop information, configuration queries, help text, warnings, etc.) are also output in JSON format:
    • Command responses: {"type": "result", ...} / {"type": "ok", ...} / {"type": "error", ...}
    • Daemon information: {"type": "info", "message": "[pty-agent] Daemon started (port 12345)"}
    • Configuration queries: {"type": "config", "content": "Current call configuration:\n ..."}
    • Help text: {"type": "help", "content": "usage: pty-agent ..."}
    • Warning messages: {"type": "warning", "message": "..."}
  2. Natural language mode — switch using --output-by-natural-language

Example Scenarios

Long-Running Process Monitoring + Midway Read + Termination

app.py exec srv -c "python server.py" --idle-timeout 3 # Start, idle-timeout to return quickly after first output
app.py read srv --lines 20 # View last 20 lines of output midway
app.py read srv --offset 1024 # Incremental read (continue from last offset)
app.py read srv --grep "ERROR" # Only see error lines
app.py kill srv # Terminate when no longer needed

Process Crash Detection

app.py exec job -c "python worker.py" --idle-timeout 5 # Start, idle-timeout to wait for output
# If the process crashes, trigger.reason is "ended", program.exit_code is non-zero, error_message contains crash info
app.py events job --last 10 # View crash event details (process_crash type)

Related Skills