pty-agent 0.1.3

An observable PTY-backed coding agent built with Rig.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# pty-agent

An ultra-minimal observable PTY-backed coding agent in Rust using Rig.

```sh
OPENAI_API_KEY=... cargo run -- "fix the failing tests"
```

The process immediately starts a persistent PTY shell and streams that PTY
directly to stdout. The terminal you watch is the same terminal the Rig agent
observes and controls. The agent has exactly one tool, `terminal`, and all work
happens by typing into that PTY.

## Model

```text
user request -> Rig agent -> terminal tool -> shared PTY view -> memory/history -> continue
```

The shell launch order is `$SHELL`, then `/bin/bash`, then `/bin/sh`.

## Terminal Tool

The only tool is `terminal`.

Actions:

- `type`
- `enter`
- `type_and_enter`
- `ctrl_c`
- `key`
- `observe`

Observe modes:

- `screen`
- `recent_output`
- `command_history`
- `command_output`
- `memory_summary`
- `full_state`

## Terminal Mirror

There is no TUI framework, side panel, or hidden execution path. PTY output is
copied byte-for-byte to stdout as it arrives. Sparse status lines are written to
stderr with a `[pty-agent]` prefix so you can see when the agent is thinking,
typing, waiting, or finished without replacing the terminal view.

## Memory

The implementation keeps:

- a live VT-rendered screen model via `vt100`
- bounded raw and cleaned scrollback
- semantic command records with full output excerpts
- a rolling long-term text summary for older commands

This is intentionally small and hackable. It favors observability over
sandboxing: YOLO mode means no confirmations, no safety prompts, and no command
blocking.

## Docker

The Docker path uses `debian:bookworm-slim` and installs Rust plus native build
dependencies needed by the Rig/OpenAI stack. Debian publishes native ARM64 and
AMD64 images, so this works cleanly on Apple Silicon without emulation.

Run the agent inside a clean container-owned `/workspace` with no host project
mounted:

```sh
OPENAI_API_KEY=... /path/to/pty-agent/scripts/run-pty-agent-docker.sh "fix the failing tests"
```

By default the image runs:

```sh
cargo install pty-agent
```

Pin a crates.io version with:

```sh
PTY_AGENT_VERSION=0.1.0 ./scripts/run-pty-agent-docker.sh "fix the failing tests"
```

Before `pty-agent` is published to crates.io, test the same container using the
local checkout:

```sh
OPENAI_API_KEY=... ./scripts/run-pty-agent-docker.sh --local "fix the failing tests"
```

To launch the same container directly into a clean shell with `pty-agent`
installed from crates.io:

```sh
./scripts/shell-pty-agent-docker.sh
```

For a Rust-only shell without installing `pty-agent`:

```sh
./scripts/shell-pty-agent-docker.sh --no-install
```

Force a full rebuild after Dockerfile changes:

```sh
./scripts/shell-pty-agent-docker.sh --rebuild
./scripts/run-pty-agent-docker.sh --rebuild "fix the failing tests"
```

For local development only, mount this checkout at `/src/pty-agent`:

```sh
./scripts/shell-pty-agent-docker.sh --local
```