This repository has no description
version bump to 0.7.0, restructured changelog, updated README (commands + skill reference), SKILL.md, flake.nix hash, package-lock
Nathan Herald
(Apr 14, 2026, 1:59 PM +0200)
2cc6a536
199e6f2f
+208
-17
+37
-13
CHANGELOG.md
+37
-13
CHANGELOG.md
···
1
1
# Changelog
2
2
3
-
## Unreleased
3
+
## 0.7.0
4
+
5
+
### Supervisor
6
+
- Add session supervisor: `pty supervisor start` runs a foreground process that watches for sessions with `strategy=permanent` tag and restarts them on exit with exponential backoff (1s→16s, max 5 restarts per 60s)
7
+
- `pty supervisor start/stop/status/forget/reset` commands
8
+
- `pty supervisor launchd install/uninstall` for macOS auto-start — bundles the supervisor into a portable JS file via esbuild, uses absolute paths to node (no PATH dependency), `KeepAlive=true`
9
+
- Supervision is configured entirely through tags (`strategy=permanent` or `strategy=temporary`)
10
+
- `strategy=permanent`: restart on exit with backoff. `strategy=temporary`: clean up on exit
11
+
- Supervisor detects dead processes via PID liveness check (handles external kills where `exitedAt` is never set)
12
+
- Supervisor state persisted in `~/.local/state/pty/supervisor/` (restart counts survive supervisor restarts)
13
+
- `pty supervisor reset <name>` clears failed status for retry
14
+
- New event types: `session_restart`, `session_failed`, `supervisor_start`, `supervisor_stop`
15
+
- 10s periodic scan as safety net for missed `fs.watch` events
4
16
17
+
### Project files
5
18
- Add `pty up` / `pty down` commands to start and stop sessions defined in a `pty.toml` project file
6
-
- `pty.toml` supports named sessions with commands and optional tags
19
+
- `pty.toml` supports named sessions with commands, tags, and an optional `prefix` for session naming
7
20
- `pty up` accepts a directory argument (`pty up ./backend`) and session name filtering (`pty up dev serve`)
8
-
- Add `--tags` flag to `pty list` to display tags as `#key=value` hashtags
9
-
- Add session supervisor: `pty supervisor start` runs a process that watches for sessions with `strategy=permanent` tag and restarts them on exit with exponential backoff
21
+
- `pty up` syncs tags from the toml to already-running sessions (without removing manually-added tags)
22
+
- `pty up` stores `ptyfile` and `ptyfile.session` tags so the supervisor re-reads the toml on restart
23
+
- `pty down` removes strategy tags and stops sessions (including supervised ones), warns about toml-managed sessions
24
+
25
+
### Mutable tags
10
26
- Add `pty tag <name> key=value` / `pty tag <name> --rm key` to set and remove tags on running or exited sessions
11
-
- Add `pty supervisor start/stop/status/forget` commands
12
-
- Add `pty supervisor launchd install/uninstall` for macOS auto-start
13
-
- Supervision is configured entirely through tags (`strategy=permanent` in pty.toml tags or via `pty tag`)
14
-
- `pty list` shows `[permanent]`, `[temporary]`, and `[failed]` markers for supervised sessions
15
-
- `pty down` refuses to stop supervised sessions (use `pty supervisor forget` first)
16
-
- New event types: `session_restart`, `session_failed`, `supervisor_start`, `supervisor_stop`
27
+
- `pty tag <name>` with no args shows current tags
28
+
- Warns when modifying tags on toml-managed sessions (changes will be overwritten by `pty up`)
17
29
- Atomic metadata writes (write-to-temp + rename) to prevent partial reads
18
-
- Add `pty peek --wait "text"` to block until text appears on screen, with optional `-t` timeout
30
+
31
+
### Peek and wait
32
+
- Add `pty peek --wait "text"` to block until text appears on screen, with optional `-t` timeout (seconds)
19
33
- Add `pty peek --full` to show full scrollback (not just viewport)
20
-
- Add `pty events --wait <type>` to block until a specific event type occurs
34
+
- Add `pty events --wait <type>` to block until a specific event type occurs, with optional `-t` timeout
35
+
36
+
### CLI improvements
37
+
- Add `--cwd` flag to `pty run` to start a session in a specific directory
38
+
- Add `--tags` flag to `pty list` to display tags as `#key=value` hashtags
21
39
- Colorize `pty list` output: bold cyan session names, dimmed commands
22
40
- Interactive TUI list shows `[permanent]`/`[temporary]`/`[failed]` markers with color
23
-
- Add `--cwd` flag to `pty run` to start a session in a specific directory without needing to `cd` first
41
+
- `pty kill` on supervised sessions removes the strategy tag (supervisor won't restart it)
42
+
- `pty kill` and `pty down` warn when stopping toml-managed sessions
43
+
44
+
### Fixes
45
+
- Defensive `meta.args` fallback to `[]` in all display code (prevents crashes on old metadata)
46
+
- Shell integration tests isolated from real session directory
47
+
- Fix flaky TUI filter test (wait for list to re-render, not just input to appear)
24
48
25
49
## 0.6.0
26
50
+16
README.md
+16
README.md
···
54
54
pty run -a -- node server.js # create or attach if already running
55
55
pty run -e -- npm test # ephemeral: auto-remove on exit
56
56
pty run --tag owner=forge -- node srv.js # tag a session with metadata
57
+
pty run --cwd /path -- node server.js # run in a specific directory
57
58
58
59
pty list # show active sessions
59
60
pty list --tags # show sessions with tags (#key=value)
···
63
64
pty attach -r myserver # reconnect, auto-restart if exited
64
65
pty peek myserver # print current screen and exit
65
66
pty peek --plain myserver # print as plain text (no ANSI)
67
+
pty peek --full myserver # print full scrollback
68
+
pty peek --wait "Listening" myserver # wait until text appears on screen
69
+
pty peek --wait "Ready" -t 10 myserver # wait with timeout (seconds)
66
70
pty peek -f myserver # follow output read-only
67
71
68
72
pty send myserver "hello" # send text (no implicit newline)
···
83
87
pty kill myserver # terminate a running session
84
88
pty rm myserver # remove an exited session's metadata
85
89
pty gc # remove all exited sessions
90
+
pty tag myserver role=web # set tags on a session
91
+
pty tag myserver --rm role # remove a tag
92
+
93
+
pty supervisor start # start the session supervisor
94
+
pty supervisor stop # stop the supervisor
95
+
pty supervisor status # show supervised sessions
96
+
pty supervisor forget myserver # stop supervising a session
97
+
pty supervisor reset myserver # reset a failed session for retry
86
98
87
99
pty up # start all sessions from ./pty.toml
88
100
pty up ./backend # start sessions from ./backend/pty.toml
···
296
308
- **agent-teams** — live dashboard of a simulated AI agent hierarchy with real-time updates
297
309
298
310
Run them with `node --experimental-strip-types demos/{name}/main.ts`. Each demo includes unit tests and PTY integration tests that exercise the testing library.
311
+
312
+
## Skill Reference
313
+
314
+
For AI coding agents and automation, see **[docs/SKILL.md](docs/SKILL.md)** — a concise guide to running and managing background processes with pty, including session lifecycle, common patterns, and rules for well-behaved agents.
299
315
300
316
## Tab Completion
301
317
+151
docs/SKILL.md
+151
docs/SKILL.md
···
1
+
# PTY — Run and manage background processes
2
+
3
+
Run `pty --help` to see the full command reference.
4
+
5
+
Use `pty` to run processes in managed terminal sessions. Prefer pty over raw
6
+
background commands (`&`, `nohup`, piping) for better lifecycle control,
7
+
readable output, and the ability to wait for results.
8
+
9
+
## When to use
10
+
11
+
- Running any long-lived or background process (dev servers, test suites, builds)
12
+
- Interactive CLI tools that need a real terminal (auth via keychain, TUI, REPL)
13
+
- Any task where you want to start work, do something else, then check results
14
+
- Processes you may need to re-read output from later
15
+
16
+
## Session lifecycle
17
+
18
+
### 1. Create a detached session
19
+
20
+
```bash
21
+
pty run -d --name <descriptive-name> --tag owner=<agent> -- <command> [args...]
22
+
```
23
+
24
+
Use `--cwd` to run in a specific directory:
25
+
26
+
```bash
27
+
pty run -d --name <name> --cwd /path/to/project --tag owner=<agent> -- <command>
28
+
```
29
+
30
+
Tag sessions so they are identifiable. Never touch sessions you did not create.
31
+
32
+
### 2. Wait for the process to be ready
33
+
34
+
```bash
35
+
pty peek --wait "expected text" --plain <name> -t 10
36
+
```
37
+
38
+
Check the output to confirm the process has started (e.g. "Authenticated",
39
+
"Listening", a prompt character).
40
+
41
+
### 3. Send input (if interactive)
42
+
43
+
```bash
44
+
pty send <name> "your message here"
45
+
pty send <name> --seq key:return
46
+
```
47
+
48
+
For multi-step input use `--seq` chains:
49
+
50
+
```bash
51
+
pty send <name> --seq "first line" --seq key:return
52
+
```
53
+
54
+
Use `--with-delay` if the tool needs time between inputs:
55
+
56
+
```bash
57
+
pty send <name> --with-delay 0.5 --seq "text" --seq key:return
58
+
```
59
+
60
+
### 4. Wait for output and read results
61
+
62
+
Wait for specific text to appear:
63
+
64
+
```bash
65
+
pty peek --wait "expected output" --plain <name> -t 120
66
+
```
67
+
68
+
Read the full scrollback (not just the visible screen):
69
+
70
+
```bash
71
+
pty peek --full --plain <name>
72
+
```
73
+
74
+
Read just the current visible screen:
75
+
76
+
```bash
77
+
pty peek --plain <name>
78
+
```
79
+
80
+
Check recent events without following:
81
+
82
+
```bash
83
+
pty events --recent <name>
84
+
```
85
+
86
+
### 5. Clean up
87
+
88
+
Always kill sessions you created when done:
89
+
90
+
```bash
91
+
pty kill <name>
92
+
```
93
+
94
+
## Rules
95
+
96
+
- **Always use `--plain` with peek** so output is readable (no ANSI escapes)
97
+
- **Always use `-t` (timeout)** on `--wait` so you don't block forever
98
+
- **Always tag sessions** so they are identifiable and attributable
99
+
- **Always clean up** — kill sessions when you are done
100
+
- **Never touch sessions you did not create** — check `pty list --tags` if unsure
101
+
- **Use `--full` when output may exceed the screen** — peek without it only
102
+
shows the visible terminal buffer
103
+
104
+
## Naming conventions
105
+
106
+
Name sessions by purpose: `gemini-review`, `test-runner`, `dev-server`, etc.
107
+
Keep names lowercase with hyphens.
108
+
109
+
## Quick reference
110
+
111
+
| Action | Command |
112
+
|---|---|
113
+
| Create detached | `pty run -d --name <n> --tag owner=<a> -- <cmd>` |
114
+
| Peek (plain) | `pty peek --plain <n>` |
115
+
| Peek (full scrollback) | `pty peek --full --plain <n>` |
116
+
| Wait for text | `pty peek --wait "text" --plain <n> -t 30` |
117
+
| Send text | `pty send <n> "text"` |
118
+
| Send enter | `pty send <n> --seq key:return` |
119
+
| Recent events | `pty events --recent <n>` |
120
+
| Follow events | `pty events <n>` |
121
+
| List sessions | `pty list --tags` |
122
+
| Kill session | `pty kill <n>` |
123
+
124
+
## Common patterns
125
+
126
+
### Run a dev server and wait for it
127
+
128
+
```bash
129
+
pty run -d --name dev-server --tag owner=agent -- npm run dev
130
+
pty peek --wait "Listening" --plain dev-server -t 30
131
+
# Server is ready — do your work
132
+
pty kill dev-server
133
+
```
134
+
135
+
### Run tests and read results
136
+
137
+
```bash
138
+
pty run -d --name tests --tag owner=agent -- npm test
139
+
pty peek --wait "passed\|failed" --plain tests -t 120
140
+
pty peek --full --plain tests
141
+
pty kill tests
142
+
```
143
+
144
+
### Run a build and check for errors
145
+
146
+
```bash
147
+
pty run -d --name build --tag owner=agent -- npm run build
148
+
pty peek --wait "error\|successfully" --plain build -t 60
149
+
pty peek --full --plain build
150
+
pty kill build
151
+
```
+1
-1
flake.nix
+1
-1
flake.nix
···
29
29
30
30
# Generated from package-lock.json.
31
31
# Regenerate with: nix run nixpkgs#prefetch-npm-deps -- package-lock.json
32
-
npmDepsHash = "sha256-a7g3tIDb+6JKQxCTqnL1i3gps4LjTVjt8wf+TrDtPzY=";
32
+
npmDepsHash = "sha256-p9vkNBkSC8lQb23b2p5Exo3n/tlJrq8wuRoSjajpZgo=";
33
33
34
34
# node-pty has native code that needs these at build time
35
35
nativeBuildInputs = with pkgs; [ python3 pkg-config ];
+2
-2
package-lock.json
+2
-2
package-lock.json
···
1
1
{
2
2
"name": "@myobie/pty",
3
-
"version": "0.6.0",
3
+
"version": "0.7.0",
4
4
"lockfileVersion": 3,
5
5
"requires": true,
6
6
"packages": {
7
7
"": {
8
8
"name": "@myobie/pty",
9
-
"version": "0.6.0",
9
+
"version": "0.7.0",
10
10
"hasInstallScript": true,
11
11
"license": "MIT",
12
12
"dependencies": {