v1.20Grok Build CLI support →

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  |     | 2. Command lands inside   |
|                            |     |    the live program       |
|  SID=$(agents pty start    | --> |                           |
|          --shell python3)  |     |  >>> import pandas        |
+----------------------------+     +---------------------------+
          |                                    |
          v                                    v
+----------------------------+     +---------------------------+
| 4. Clean text comes back   |     | 3. Python responds        |
|                            |     |                           |
|  agents pty screen $SID    | <-- |  >>>                      |
|  > import pandas           |     |  (module loaded, no error)|
+----------------------------+     +---------------------------+

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