This repository has no description
Wire up events subcommand and fix stats with older processes
Nathan Herald
(Apr 6, 2026, 3:43 PM +0200)
b7f7c325
d3751161
+31
-4
+25
-1
README.md
+25
-1
README.md
···
70
70
71
71
pty stats # live metrics for all sessions
72
72
pty stats myserver # stats for a specific session
73
-
pty stats --json # stats as JSON
73
+
pty stats --json # stats as JSON (includes CPU, memory, PIDs)
74
+
75
+
pty events myserver # follow events in real-time
76
+
pty events --all # follow events from all sessions
77
+
pty events --recent myserver # show recent events and exit
78
+
pty events --json myserver # output raw JSONL
74
79
75
80
pty restart myserver # restart an exited session
76
81
pty kill myserver # terminate a running session
···
99
104
```
100
105
101
106
Detach with `Ctrl+\`. (Press `Ctrl+\` twice to send it through to the process.)
107
+
108
+
### Nesting Prevention
109
+
110
+
If you run `pty run` (or a wrapped command) inside an existing pty session, pty detects the nesting via the `PTY_SESSION` environment variable and runs the command directly instead of creating a session-inside-a-session. This means wrapped commands "just work" inside pty sessions without double-wrapping.
111
+
112
+
Use `pty run -d` to explicitly create a background session from inside another session.
113
+
114
+
### Events
115
+
116
+
Sessions automatically log terminal events — bell, title changes, desktop notifications (OSC 9/99/777), focus requests, and cursor visibility transitions — to per-session JSONL files.
117
+
118
+
```sh
119
+
pty events myserver # follow events live (like tail -f)
120
+
pty events --all # follow all sessions, interleaved
121
+
pty events --recent myserver # dump recent events and exit
122
+
pty events --json myserver # raw JSONL output
123
+
```
124
+
125
+
Event files auto-truncate at 1,000 lines and are cleaned up with the 24-hour dead session TTL.
102
126
103
127
## Testing Library
104
128
+6
-3
src/cli.ts
+6
-3
src/cli.ts
···
741
741
console.log(` Command: ${cmd}`);
742
742
console.log(` CWD: ${cwd}`);
743
743
console.log(` Uptime: ${formatUptime(stats.uptimeSeconds)}`);
744
-
console.log(` Process: ${stats.process.alive ? "running" : `exited (code ${stats.process.exitCode})`}${stats.process.pid ? ` (pid ${stats.process.pid})` : ""}`);
745
-
if (stats.process.resources) {
744
+
const pidSuffix = stats.process?.pid ? ` (pid ${stats.process.pid})` : "";
745
+
console.log(` Process: ${stats.process.alive ? "running" : `exited (code ${stats.process.exitCode})`}${pidSuffix}`);
746
+
if (stats.process?.resources) {
746
747
console.log(` CPU: ${stats.process.resources.cpuPercent.toFixed(1)}%`);
747
748
console.log(` Memory: ${formatMemory(stats.process.resources.rssKb)}`);
748
749
}
749
-
console.log(` Daemon: pid ${stats.daemon.pid}${stats.daemon.resources ? `, ${formatMemory(stats.daemon.resources.rssKb)}` : ""}`);
750
+
if (stats.daemon) {
751
+
console.log(` Daemon: pid ${stats.daemon.pid}${stats.daemon.resources ? `, ${formatMemory(stats.daemon.resources.rssKb)}` : ""}`);
752
+
}
750
753
console.log(` Terminal: ${stats.terminal.cols}x${stats.terminal.rows}`);
751
754
console.log(` Cursor: row ${stats.terminal.cursorY}, col ${stats.terminal.cursorX}`);
752
755
console.log(` Scrollback: ${stats.terminal.scrollbackUsed} / ${stats.terminal.scrollbackCapacity} lines`);