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
| Command | Purpose | Typical Options | Example |
|---|---|---|---|
start/stop | Manually 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, --grep | read myid --lines 10 |
list | List all sessions | ||
kill <session-id> | Terminate a session | ||
events <session-id> [options] | View session events | --last <N>, `--since <iso-datetime | HH:MM>` |
closewin <session-id> <window-handle> | Close a GUI window; <window-handle> supports decimal or 0x hexadecimal |
Return Conditions for Command send
| Mode | Condition | Returned Information |
|---|---|---|
| With trigger | Regex matched | Incremental output |
| With idle-timeout | Idle timeout | Incremental output |
| With timeout | Timeout reached | Incremental output |
| None | Default timeout reached | Incremental output |
| GUI detection not disabled | GUI window detected (subprocess may not be available) | GUI window info + incremental output |
| Process crashed | Related events + incremental output | |
| Program exited | Incremental 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>Supportscmd/powershell/pwsh/bash(default PowerShell, falls back to CMD automatically if environment does not support it); terminal can only be configured atexecstartup--ptyEnable full pseudo-terminal (does not support shell syntax like|,&&)--force-pty-modeIgnore shell operator detection when--ptyis 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-outputStart 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--fullReturn all terminal data (large data, prefer--lines N)--json-escapingJSON 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:endRange of lines--grep "<regex>"Regex filter--offset <bytes>Incremental read--fullReturn 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-ansiPreserve control codes--colorEnable terminal color output--output-by-natural-languageNatural language output--encoding <encoding>Terminal encoding, set toutf-8/gbk/gb2312/gb18030/big5for garbled characters--no-debugDisable 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 oron/off)
Output Format
- 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": "..."}
- Command responses:
- 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)