v1.20.64see what's new →

PTY

Run a Python REPL, a database shell, or any program that expects a real terminal — and let the agent type into it and read what comes back.

How it works

Start a session, give it a program (or leave it as your default shell), then send keystrokes and read the screen. Every session runs independently; you can have several open at once.

  1. Agent starts a session
    SID=$(agents pty start --shell python3)
  2. Command lands inside the live program
    >>> import pandas
  3. Python responds
    module loaded, no error
  4. Clean text comes back to the agent
    agents pty screen $SID → > import pandas

Start a session

SID=$(agents pty start)
# or launch a specific program:
SID=$(agents pty start --shell python3)
SID=$(agents pty start --shell node --cols 160 --rows 40)

The session ID is a short random string. Store it in a variable and pass it to every subsequent command. List active sessions with agents pty list.

Read and write

agents pty write $SID "import math\n"     # \n is sent as a real newline
agents pty write $SID "math.sqrt(144)\n"
agents pty screen $SID                     # clean text snapshot: 12.0

agents pty exec $SID "git log --oneline -5" --wait 500   # fire + wait + screen
agents pty read $SID --ms 300               # raw output, up to 300ms of new bytes

Use write for keystrokes and multi-line input. Use exec for fire-and-wait convenience. Use screen for the clean snapshot the agent reads — it strips color codes and cursor noise so the output is plain text.

Worked example: Python REPL

SID=$(agents pty start --shell python3)
sleep 1 && agents pty screen $SID    # see the >>> prompt

agents pty write $SID "def greet(name):\n    return f'hello, {name}'\n\n"
agents pty write $SID "greet('world')\n"
sleep 0.5 && agents pty screen $SID  # see: 'hello, world'

agents pty stop $SID

Control and cleanup

agents pty signal $SID INT         # send Ctrl-C
agents pty signal $SID TERM        # terminate the program
agents pty resize $SID -r 40 -c 200
agents pty stop $SID               # stop the session and free resources
agents pty server status           # PID, session count, log path

Why a real terminal

Most interactive programs — Python, Node, psql, npm interactive wizards — check whether they are attached to a real terminal before they start. If they detect a pipe or a plain subprocess, they either refuse to run or switch into a dumb batch mode that drops prompts entirely. agents pty gives them the real terminal they expect, then exposes plain-text views of what is on screen so the agent can react without needing to parse color codes.

The server that manages sessions auto-starts the first time you run any pty command. You do not need to start it manually.

Related