@mentiko/pty-mgr 1.2.3

package/README.md

@@ -0,0 +1,206 @@
+# pty-mgr
+
+PTY session manager with terminal emulation for programmatic session control.
+
+Spawn commands in real pseudo-terminals, capture rendered screen output (not raw
+bytes), and manage sessions through a persistent daemon. Single binary, no
+external dependencies.
+
+## How It Works
+
+`Bun.spawn({ terminal })` allocates a native PTY for each session. An
+`@xterm/headless` terminal emulator parses escape codes, cursor movements, and
+screen redraws so `capture()` returns exactly what you'd see on screen.
+
+Compiles to a single self-contained binary via `bun build --compile`.
+
+## Install
+
+### Binary (no dependencies)
+
+```
+curl -fsSL https://raw.githubusercontent.com/maarco/pty-mgr/main/install.sh | sh
+```
+
+Installs to `~/.pty-mgr/bin/` and adds to PATH. Works on Linux and macOS (x64, arm64).
+
+### Bun package (for library use)
+
+```
+bun add pty-mgr
+```
+
+Requires [Bun](https://bun.sh) runtime.
+
+## Quick Start
+
+### As a library
+
+```js
+import { PtyManager } from 'pty-mgr';
+
+const mgr = new PtyManager();
+mgr.spawn('my-session', 'zsh', [], { cols: 120, rows: 30 });
+mgr.sendKeys('my-session', 'echo hello\r');
+
+// rename a running session
+mgr.rename('my-session', 'my-session-renamed');
+
+// wait for output, then capture rendered screen
+setTimeout(() => {
+  console.log(mgr.capture('my-session-renamed', 5));
+  mgr.kill('my-session-renamed');
+}, 1000);
+```
+
+### As a CLI
+
+```
+# start the daemon (forks to background)
+p daemon
+
+# named daemon for isolated environments
+p daemon @myproject
+
+# spawn a session
+# auto-incrementing session named after current directory
+p wrap                    # spawns as pty-mgr-1
+p wrap                    # spawns as pty-mgr-2
+p wrap                    # spawns as pty-mgr-3
+p spawn agent-1 claude --print
+
+# send keystrokes
+p send agent-1 "fix the login bug"
+
+# capture rendered screen (last 20 lines)
+p capture agent-1 20
+
+# attach interactively (ctrl-] to detach)
+p attach agent-1
+
+# rename a session
+p rename agent-1 agent-refactored
+
+# bulk operations with globs
+p capture all 50
+p kill refa*
+
+# stop daemon
+p stop
+```
+
+### CLI Aliases
+
+| Short | Full    | Short | Full    |
+|-------|---------|-------|---------|
+| n/new  | spawn   | w/wrap  | wrap    |
+| s      | send    | k       | kill    |
+| c/cap  | capture | l/ls    | list    |
+| a      | attach  | r/rm    | remove  |
+| st     | status  | mv/ren  | rename  |
+| i      | info    | d       | daemon  |
+| cfg    | config  | x       | stop    |
+
+## Managed CLI Sessions
+
+Wrap any CLI tool (claude, codex, gemini, etc.) in managed PTY sessions.
+Run the interactive setup:
+
+```
+pty-mgr setup
+```
+
+It asks which commands to wrap, then adds shell functions to your rc file.
+After that, just type `claude` like normal. What you get:
+
+- Claude runs inside a managed PTY session named `<folder>-1`
+- If you open another claude in the same folder, it gets `<folder>-2`
+- `ctrl-]` to detach -- Claude keeps running in the background
+- `p attach <name>` to jump back in
+- `p capture <name> 50` to check on it from another terminal
+- `p list` to see all your Claude sessions across all projects
+
+```
+$ cd ~/dev/my-app
+$ claude                     # spawns as my-app-1, attaches
+  ctrl-]                     # detach
+$ claude                     # spawns as my-app-2
+  ctrl-]
+$ p list
+my-app-1  pid=1234  120x40  alive  claude
+my-app-2  pid=1235  120x40  alive  claude
+$ p capture my-app-1 20      # peek at what agent 1 is doing
+$ p attach my-app-1          # jump back into agent 1
+```
+
+### Programmatic (parallel agents)
+
+```js
+import { PtyManager } from 'pty-mgr';
+
+const mgr = new PtyManager();
+
+// launch 3 Claude agents in parallel
+const agents = ['auth-fix', 'api-tests', 'docs-update'];
+for (const name of agents) {
+  mgr.spawn(name, 'claude', ['--print'], { cols: 120, rows: 40 });
+}
+
+mgr.sendKeys('auth-fix', 'fix the login bug in src/auth.ts\r');
+mgr.sendKeys('api-tests', 'write tests for the /users endpoint\r');
+mgr.sendKeys('docs-update', 'update the API docs in README.md\r');
+
+// poll until all agents finish
+for (const name of agents) {
+  await mgr.waitFor(name, /[✔✓]|completed|done/i, 120000);
+  console.log(`${name} done:\n${mgr.capture(name, 10)}\n`);
+}
+
+mgr.destroyAll();
+```
+
+## Daemon Protocol
+
+The daemon listens on a Unix socket at `~/.pty-manager/<name>.sock`.
+Communication is newline-delimited JSON:
+
+```json
+{"cmd": "spawn", "name": "agent-1", "args": {"cmd": "zsh"}}
+{"cmd": "wrap", "args": {"cmd": "zsh", "cwd": "/Users/you/dev/myproject"}}
+{"cmd": "send", "name": "agent-1", "args": {"text": "echo hi\r"}}
+{"cmd": "capture", "name": "agent-1", "args": {"lines": 20}}
+{"cmd": "list"}
+{"cmd": "kill", "name": "agent-1"}
+{"cmd": "rename", "name": "agent-1", "args": {"newName": "agent-refactored"}}
+{"cmd": "shutdown"}
+```
+
+The `attach` command switches the connection to raw streaming mode for
+interactive use.
+
+## Configuration
+
+```
+p config screen 120x40       # default terminal size for new sessions
+p config cap-on-send on      # return capture with every send command
+```
+
+## Logging
+
+```
+p spawn agent-1 --log claude   # spawn with auto-logging (jsonl)
+p log agent-1 on jsonl         # start logging an existing session
+p log agent-1 off              # stop logging
+```
+
+Formats: `jsonl` (timestamped events), `raw` (PTY bytes), `rendered` (screen snapshots).
+
+## Build
+
+```
+bun run build    # compiles to dist/pty-mgr (single binary, ~60MB)
+```
+
+## License
+
+MIT

package/bin/pty-mgr

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+// Binary launcher for pty-mgr.
+// Finds the platform-specific binary installed via optionalDependencies
+// and executes it with the same args.
+
+import { execFileSync } from "child_process";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { createRequire } from "module";
+import { fileURLToPath } from "url";
+
+const require = createRequire(import.meta.url);
+
+const PLATFORMS = {
+  "linux-x64": "@mentiko/pty-mgr-linux-x64",
+  "linux-arm64": "@mentiko/pty-mgr-linux-arm64",
+  "darwin-x64": "@mentiko/pty-mgr-darwin-x64",
+  "darwin-arm64": "@mentiko/pty-mgr-darwin-arm64",
+};
+
+function getBinaryPath() {
+  const key = `${process.platform}-${process.arch}`;
+  const pkg = PLATFORMS[key];
+
+  if (!pkg) {
+    console.error(
+      `pty-mgr: unsupported platform ${process.platform}-${process.arch}`
+    );
+    console.error("supported: linux-x64, linux-arm64, darwin-x64, darwin-arm64");
+    process.exit(1);
+  }
+
+  // try to find the binary from the installed optional dep
+  try {
+    const pkgDir = dirname(require.resolve(`${pkg}/package.json`));
+    const bin = join(pkgDir, "pty-mgr");
+    if (existsSync(bin)) return bin;
+  } catch {}
+
+  // fallback: check ~/.pty-mgr/bin/ (install.sh location)
+  const homeBin = join(
+    process.env.HOME || process.env.USERPROFILE || "",
+    ".pty-mgr",
+    "bin",
+    "pty-mgr"
+  );
+  if (existsSync(homeBin)) return homeBin;
+
+  console.error("pty-mgr: binary not found");
+  console.error("");
+  console.error("install it:");
+  console.error(
+    "  curl -fsSL https://raw.githubusercontent.com/kollaborai/pty-mgr/main/install.sh | sh"
+  );
+  console.error("");
+  console.error("or reinstall this package:");
+  console.error("  npm install -g @mentiko/pty-mgr");
+  process.exit(1);
+}
+
+const bin = getBinaryPath();
+
+try {
+  execFileSync(bin, process.argv.slice(2), {
+    stdio: "inherit",
+    env: process.env,
+  });
+} catch (e) {
+  process.exit(e.status || 1);
+}