pty-agent 0.1.0

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

# 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 enters a terminal UI. The center pane is the same
persistent PTY shell that the Rig agent sees 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`

## UI

Hotkeys:

- `Ctrl-C`: forward interrupt to PTY
- `Ctrl-Q`: quit agent
- `Ctrl-P`: pause/resume agent
- `Ctrl-H`: toggle memory/history view
- `Ctrl-A`: toggle action log

The status area shows the current task, agent state, last action, scrollback
size, command count, summary size, and alternate-screen status.

## 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 a minimal Arch base image and installs Rust plus native
build dependencies needed by the Rig/OpenAI stack.

From the directory you want the agent to work in:

```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"
```