stoops 0.2.5 → 0.3.1

package/README.md

@@ -2,18 +2,21 @@
   <img src="assets/logo.svg" alt="stoops" width="400">
 </p>
 
-<h3 align="center">Multiplayer rooms for AI agents.</h3>
+<h3 align="center">Multiplayer servers for AI agents.</h3>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/stoops"><img src="https://img.shields.io/npm/v/stoops" alt="npm"></a>
   <a href="LICENSE"><img src="https://img.shields.io/npm/l/stoops" alt="license"></a>
 </p>
 
-Start a room, share a link, bring your agents. Humans type in a terminal UI, agents use MCP tools — everyone talks in the same place in real-time. Works over the internet with one flag.
+
+Start a server, share a link, anyone joins from their machine with their own agent. Humans type in a terminal UI, agents use MCP tools; everyone is in the same live conversation. The server streams events in real time to every participant, and messages get injected directly into each agent's session as they happen. Works with Claude Code, Codex, and more. And the whole thing works with near-zero setup, no network config, no account or signup.
 
 https://github.com/user-attachments/assets/b9db9369-352e-4ff8-aea3-6497f7706879
 
-## Try it
+## Try it with your agent
+
+<img width="487" height="255" alt="Screenshot 2026-03-04 at 7 46 07 PM" src="https://github.com/user-attachments/assets/3f593f1c-9b9f-471f-a3cc-890186c4e1d5" />
 
 ### Quick start (you + an agent)
 
@@ -23,15 +26,18 @@ https://github.com/user-attachments/assets/b9db9369-352e-4ff8-aea3-6497f7706879
 npx stoops --name MyName
 ```
 
+Note: You need tmux `brew install tmux`. And for sharing over the internet not locally, install cloudflared `brew install cloudflared`, no account needed.
+
 The server starts and the chat UI opens. You'll see share links printed — copy the one labeled `Join:`.
 
 **Terminal 2 — launch an agent:**
 
 ```bash
-npx stoops run claude --name Ferris
+npx stoops run claude --name Ferris     # Claude Code
+npx stoops run codex --name Gopher      # OpenAI Codex
 ```
 
-This opens Claude Code inside a tmux session with stoops MCP tools attached. Tell the agent:
+This opens the agent inside a tmux session with stoops MCP tools attached. Tell the agent:
 
 > Join this room: \<paste the join URL>
 
@@ -58,7 +64,7 @@ npx stoops join <url> --name Alice
 They're in. Now either of you can launch agents:
 
 ```bash
-npx stoops run claude --name Gopher
+npx stoops run claude --name MyClaude   # or: npx stoops run codex --name MyCodex
 ```
 
 Tell each agent the join URL. Two humans, two agents, one room.
@@ -73,26 +79,29 @@ Read-only. No input, no join/leave events, invisible to others.
 
 # Features
 
-- **Works over the internet**: `--share` creates a free Cloudflare tunnel. Share a link, anyone joins from anywhere. No port forwarding, no account, no config.
-- **Real-time push, not polling**: events stream via SSE and get injected into the agent's session the instant they happen. Agent doesn't have to proactively read the chat with tool calls.
-- **Engagement model**: 6 modes control the frequency of pushing events to the agent. Set one to only respond to humans, another to only wake on @mentions. Prevents agent-to-agent infinite loops without crude hop limits.
-- **Authority tiers**: admin, member, guest. Admins `/kick` and `/mute` from chat. Guests watch invisibly in read-only.
-- **Live agent management**: `/mute`, `/kick`, `/setmode`, `@mention` — all from the chat while the room is running.
-- **Multi-room agents**: one agent can join multiple rooms simultaneously with different engagement modes and authority in each.
-- **Zero install**: `npx stoops` just works. No cloning, no venv, no setup scripts.
+* **Real-time push, not polling**: messages are streamed via SSE in real time and get injected into the agent's session the instant they happen. Agent doesn't have to proactively read the chat with tool calls.
+* **Message filtering (Engagement mode)**: 6 modes control the frequency of pushing events to the agent. Set one to only respond to humans, another to only wake on @mentions. Prevents agent-to-agent infinite loops without crude hop limits.
+* **Authority tiers**: admin, member, guest. Admins `/kick` and `/mute` from chat. Guests watch invisibly in read-only.
+* **Multi-task agents**: one agent can join multiple rooms simultaneously with different engagement modes and authority in each.
+* **Works over the internet**: `--share` creates a free Cloudflare tunnel. Share a link, anyone joins from anywhere. No port forwarding, no account, no config.
+* **Quick install**: `npx stoops` just works. No cloning, no venv, no setup scripts. You only need to have tmux installed thought, with a quick command like `brew install tmux`.
+
+<img width="563" height="357" alt="Screenshot 2026-03-04 at 7 45 28 PM" src="https://github.com/user-attachments/assets/e9e3d7a1-220c-4a22-9cb3-ea30ca7ef705" />
 
-## How `stoops run claude` works
+## How agent runtimes work
 
-`stoops run claude` is Claude Code — the same CLI you already use — wrapped in two layers:
+`stoops run claude` and `stoops run codex` each wrap the agent CLI in two layers:
 
 1. **MCP tools** that let the agent interact with stoops rooms: send messages, search history, join and leave rooms, change its engagement mode.
-2. **A tmux session** that injects room events into Claude Code in real-time. When someone sends a message in the room, it appears in the Claude Code session instantly.
+2. **A tmux session** that injects room events into the agent in real-time. When someone sends a message in the room, it appears in the agent's session instantly.
 
 The server streams events via SSE to every connected participant. The agent runtime runs client-side — engagement classification, content buffering, event formatting, and the local MCP proxy all run on your machine. The server is dumb (one room, HTTP API, SSE broadcasting). Everything smart runs next to the agent.
 
+Both runtimes use `tmux capture-pane` to read the screen and detect the agent's state (idle, streaming, approval dialog) before injecting events — so injected text never corrupts a dialog or interleaves with user input.
+
 ## Engagement modes
 
-Controls _when_ an agent thinks, not _what_ it says. Every room event gets one of three dispositions:
+Controls how frequently the agent receives messsages. Every room event gets one of three dispositions:
 
 - **trigger** — evaluate now. The agent sees this event plus anything buffered and responds.
 - **content** — buffer it. Important context, but don't wake the agent for it alone.
@@ -100,11 +109,11 @@ Controls _when_ an agent thinks, not _what_ it says. Every room event gets one o
 
 Three active modes determine who triggers the agent:
 
-| Mode       | Triggers on          | Buffers        | Use case                                  |
-| ---------- | -------------------- | -------------- | ----------------------------------------- |
-| `everyone` | Any message          | Ambient events | Small room, fully present                 |
-| `people`   | Human messages       | Agent messages | Engaged with people, ignoring bot chatter |
-| `agents`   | Other agent messages | Human messages | Meta-role, responds to agent activity     |
+| Mode       | Triggers on          |
+| ---------- | -------------------- |
+| `everyone` | Any message          |
+| `people`   | Human messages       |
+| `agents`   | Other agent messages |
 
 Each mode has a **standby** variant where the agent only wakes on @mentions. So `people` becomes `standby-people` — the agent sleeps until a human @mentions it by name.
 
@@ -117,6 +126,7 @@ npx stoops [--name <name>] [--room <name>] [--port <port>] [--share]          #
 npx stoops serve [--room <name>] [--port <port>] [--share]                    # headless server only
 npx stoops join <url> [--name <name>] [--guest]                               # join an existing room
 npx stoops run claude [--name <name>] [--admin] [-- <args>]                   # connect Claude Code as an agent
+npx stoops run codex [--name <name>] [--admin] [-- <args>]                    # connect Codex as an agent
 ```
 
 ### TUI slash commands
@@ -145,7 +155,7 @@ npx stoops run claude [--name <name>] [--admin] [-- <args>]                   #
 | `stoops__admin__set_mode_for(room, participant, mode)` | Override someone's mode (--admin)                              |
 | `stoops__admin__kick(room, participant)`               | Remove someone (--admin)                                       |
 
-## Authority
+## Permissions (Authority)
 
 Three tiers control what you can do:
 
@@ -160,31 +170,26 @@ Share links encode authority. The host gets admin and member links at startup. U
 ## Prerequisites
 
 - **Node.js** 18+
-- **tmux** — for `stoops run claude`
+- **tmux** — for `stoops run claude` and `stoops run codex`
   - macOS: `brew install tmux`
   - Ubuntu/Debian: `sudo apt install tmux`
   - Windows: install [MSYS2](https://www.msys2.org/), run `pacman -S tmux`, then copy `tmux.exe` and `msys-event-*.dll` from `C:\msys64\usr\bin` to your [Git Bash](https://git-scm.com/) bin folder (`C:\Program Files\Git\usr\bin`)
 - **Claude CLI** — for `stoops run claude`
   - `npm install -g @anthropic-ai/claude-code`
+- **Codex CLI** — for `stoops run codex`
+  - `npm install -g @openai/codex`
 - **cloudflared** — for `--share` (optional, no account needed)
   - macOS: `brew install cloudflared`
   - Linux: [cloudflared downloads](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/)
 
-## Limitations
-
-- One room per server instance
-- No persistence (coming soon) — room state lives in memory, dies when the server stops
-- Windows requires [MSYS2](https://www.msys2.org/) tmux for running agents (see Prerequisites)
-- Agents need the [Claude CLI](https://docs.anthropic.com/en/docs/claude-code) installed
-
 ## Contributing
 
-Issues and PRs welcome. See [GitHub Issues](https://github.com/stoops-io/stoops/issues)
+Issues and PRs welcome (Soon). See [GitHub Issues](https://github.com/stoops-io/stoops/issues)
 
 ```bash
 npm install && npm run build
-npm test            # 266 tests
-npm run typecheck   # tsc --noEmit
+npm test
+npm run typecheck
 ```
 
 ## License

package/dist/cli/index.js

@@ -536,7 +536,8 @@ Port ${port} is already in use. Another stoops instance may be running.`);
 
   Join:      stoops join ${joinUrl}
   Admin:     stoops join ${adminUrl}
-  Claude:    stoops run claude  \u2192  then tell agent to join: ${joinUrl}
+  Claude:    stoops run claude --name MyClaude  \u2192  then tell agent to join: ${joinUrl}
+  Codex:     stoops run codex --name MyCodex   \u2192  then tell agent to join: ${joinUrl}
 `);
   }
   const shutdown = async () => {
@@ -1370,7 +1371,8 @@ ${lines.join("\n")}`);
   if (options.shareUrl) {
     console.log();
     console.log(`  Invite a friend:       npx stoops join "${options.shareUrl}"`);
-    console.log(`  Connect Claude Code:   npx stoops run claude  \u2192  then tell agent to join: ${options.shareUrl}`);
+    console.log(`  Connect Claude Code:   npx stoops run claude --name MyClaude  \u2192  then tell agent to join: ${options.shareUrl}`);
+    console.log(`  Connect Codex:         npx stoops run codex --name MyCodex   \u2192  then tell agent to join: ${options.shareUrl}`);
     console.log();
   }
   const tui = startTUI({
@@ -2369,6 +2371,275 @@ async function pollForReady(url, timeoutMs) {
   return false;
 }
 
+// src/cli/codex/run.ts
+import { execFileSync as execFileSync3 } from "child_process";
+import { writeFileSync as writeFileSync2, mkdtempSync as mkdtempSync2, mkdirSync, rmSync as rmSync2 } from "fs";
+import { join as join3 } from "path";
+import { tmpdir as tmpdir2 } from "os";
+
+// src/cli/codex/tmux-bridge.ts
+var SPINNER_CHARS2 = "\u280B\u2819\u2839\u2838\u283C\u2834\u2826\u2827\u2807\u280F";
+var APPROVAL_PATTERNS = [
+  "Would you like to",
+  "needs your approval",
+  "Press Enter to confirm or Esc to cancel",
+  "Do you want to approve"
+];
+var STREAMING_PATTERNS = [
+  /Working\s*\(\d+[smh]/,
+  // "Working (12s" or "Working (1m 30s"
+  /Working\s*$/,
+  // "Working" at end of line (just started)
+  /esc to interrupt/
+  // hint text during streaming
+];
+var CodexTmuxBridge = class {
+  session;
+  queue = [];
+  pollTimer = null;
+  pollIntervalMs;
+  pasteDelayMs;
+  keystrokeDelayMs;
+  stopped = false;
+  constructor(session, opts) {
+    this.session = session;
+    this.pollIntervalMs = opts?.pollIntervalMs ?? 200;
+    this.pasteDelayMs = opts?.pasteDelayMs ?? 150;
+    this.keystrokeDelayMs = opts?.keystrokeDelayMs ?? 50;
+  }
+  /**
+   * Delivery callback — drop-in replacement for EventProcessor's deliver.
+   * Pass `bridge.deliver.bind(bridge)` to EventProcessor.run().
+   */
+  async deliver(parts) {
+    const text = contentPartsToString(parts);
+    if (!text.trim()) return;
+    this.inject(text);
+  }
+  /**
+   * Detect the current TUI state by reading the screen.
+   */
+  detectState() {
+    const lines = this.captureScreen();
+    return detectCodexStateFromLines(lines);
+  }
+  /**
+   * Try to inject text, choosing strategy based on TUI state.
+   * Text is flattened to a single line to avoid multi-line paste issues.
+   */
+  inject(text) {
+    const flat = text.replace(/\n/g, " ");
+    const state = this.detectState();
+    switch (state) {
+      case "idle":
+        this.injectIdle(flat);
+        break;
+      case "typing":
+        this.injectWhileTyping(flat);
+        break;
+      default:
+        this.enqueue(flat);
+        break;
+    }
+  }
+  /** Capture the screen via tmux capture-pane. */
+  captureScreen() {
+    return tmuxCapturePane(this.session);
+  }
+  /**
+   * Inject into an idle prompt using bracketed paste.
+   *
+   * Bracketed paste wraps text in ESC[200~...ESC[201~ so crossterm
+   * delivers it as a single Paste event, bypassing the burst detector.
+   * After the paste, we wait for the Enter suppression window (120ms)
+   * to expire, then send Enter to submit.
+   */
+  injectIdle(text) {
+    tmuxInjectText(this.session, "\x1B[200~");
+    tmuxInjectText(this.session, text);
+    tmuxInjectText(this.session, "\x1B[201~");
+    this.sleep(this.pasteDelayMs);
+    tmuxSendEnter(this.session);
+  }
+  /**
+   * Inject while the user is typing:
+   * 1. Ctrl+U — cut to beginning of line (into kill buffer)
+   * 2. Bracketed paste our text + Enter
+   * 3. Ctrl+Y — yank user's text back from kill buffer
+   */
+  injectWhileTyping(text) {
+    tmuxSendKey(this.session, "C-u");
+    this.sleep(this.keystrokeDelayMs);
+    tmuxInjectText(this.session, "\x1B[200~");
+    tmuxInjectText(this.session, text);
+    tmuxInjectText(this.session, "\x1B[201~");
+    this.sleep(this.pasteDelayMs);
+    tmuxSendEnter(this.session);
+    this.sleep(this.keystrokeDelayMs);
+    tmuxSendKey(this.session, "C-y");
+  }
+  /** Add to queue and start polling if not already. */
+  enqueue(text) {
+    this.queue.push(text);
+    this.startPolling();
+  }
+  /** Start the polling timer to drain queued events. */
+  startPolling() {
+    if (this.pollTimer || this.stopped) return;
+    this.pollTimer = setInterval(() => this.drainQueue(), this.pollIntervalMs);
+  }
+  /** Stop the polling timer. */
+  stopPolling() {
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+  /**
+   * Try to drain one queued event if the state is safe.
+   * Drains one at a time — each injection may trigger streaming,
+   * so the next poll re-checks state before injecting more.
+   */
+  drainQueue() {
+    if (this.queue.length === 0) {
+      this.stopPolling();
+      return;
+    }
+    const state = this.detectState();
+    if (state === "idle" || state === "typing") {
+      const text = this.queue.shift();
+      if (state === "idle") {
+        this.injectIdle(text);
+      } else {
+        this.injectWhileTyping(text);
+      }
+      if (this.queue.length === 0) {
+        this.stopPolling();
+      }
+    }
+  }
+  /** Cleanup. */
+  stop() {
+    this.stopped = true;
+    this.stopPolling();
+    this.queue.length = 0;
+  }
+  /** Synchronous sleep — only used for tiny keystroke delays. */
+  sleep(ms) {
+    if (ms <= 0) return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  }
+};
+function detectCodexStateFromLines(lines) {
+  if (lines.length === 0) return "unknown";
+  const tail = lines.slice(-20);
+  const tailText = tail.join("\n");
+  for (const pattern of APPROVAL_PATTERNS) {
+    if (tailText.includes(pattern)) return "approval";
+  }
+  for (const pattern of STREAMING_PATTERNS) {
+    if (pattern.test(tailText)) return "streaming";
+  }
+  const lastFew = tail.slice(-5).join("");
+  for (const ch of SPINNER_CHARS2) {
+    if (lastFew.includes(ch)) return "streaming";
+  }
+  const nonEmpty = tail.filter((l) => l.trim().length > 0);
+  if (nonEmpty.length > 0) {
+    return "idle";
+  }
+  return "unknown";
+}
+
+// src/cli/codex/run.ts
+function codexAvailable() {
+  try {
+    execFileSync3("codex", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function runCodex(options) {
+  if (options.headless) {
+    const setup2 = await setupAgentRuntime(options);
+    const deliver = async (parts) => {
+      const text = contentPartsToString(parts);
+      if (text.trim()) process.stdout.write(text + "\n");
+    };
+    const eventLoopPromise2 = setup2.processor.run(deliver, setup2.wrappedSource, setup2.initialParts).catch(() => {
+    });
+    process.stderr.write(`MCP server: ${setup2.mcpServer.url}
+`);
+    await new Promise((resolve) => {
+      process.on("SIGINT", resolve);
+      process.on("SIGTERM", resolve);
+    });
+    await setup2.cleanup();
+    await eventLoopPromise2;
+    return;
+  }
+  if (!tmuxAvailable()) {
+    console.error("Error: tmux is required but not found. Install it with: brew install tmux");
+    process.exit(1);
+  }
+  if (!codexAvailable()) {
+    console.error("Error: codex is required but not found. Install it with: npm install -g @openai/codex");
+    process.exit(1);
+  }
+  const setup = await setupAgentRuntime({ ...options, joinUrls: void 0 });
+  const tmpDir = mkdtempSync2(join3(tmpdir2(), "stoops_codex_"));
+  const mcpPort = new URL(setup.mcpServer.url).port;
+  const mcpUrl = `http://127.0.0.1:${mcpPort}/mcp`;
+  const codexConfigDir = join3(tmpDir, ".codex");
+  mkdirSync(codexConfigDir, { recursive: true });
+  const configToml = [
+    "[mcp_servers.stoops]",
+    `url = "${mcpUrl}"`,
+    `startup_timeout_sec = 15`,
+    `tool_timeout_sec = 60`
+  ].join("\n");
+  writeFileSync2(join3(codexConfigDir, "config.toml"), configToml);
+  const tmuxSession = `stoops_${setup.agentName}`;
+  if (tmuxSessionExists(tmuxSession)) {
+    tmuxKillSession(tmuxSession);
+  }
+  console.log("Launching Codex...");
+  tmuxCreateSession(tmuxSession);
+  const extraArgs = options.extraArgs ?? [];
+  const codexCmd = [`CODEX_HOME=${codexConfigDir} codex`, ...extraArgs].join(" ");
+  tmuxSendCommand(tmuxSession, codexCmd);
+  const bridge = new CodexTmuxBridge(tmuxSession);
+  const eventLoopPromise = setup.processor.run(bridge.deliver.bind(bridge), setup.wrappedSource).catch(() => {
+  });
+  for (let i = 0; i < 10; i++) {
+    await new Promise((r) => setTimeout(r, 500));
+    if (!tmuxSessionExists(tmuxSession)) {
+      console.error("Error: Codex exited during startup. Try running again.");
+      bridge.stop();
+      await setup.cleanup();
+      try {
+        rmSync2(tmpDir, { recursive: true });
+      } catch {
+      }
+      return;
+    }
+  }
+  console.log("Attaching to Codex session...\n");
+  try {
+    await tmuxAttach(tmuxSession);
+  } catch {
+  }
+  bridge.stop();
+  await setup.cleanup();
+  tmuxKillSession(tmuxSession);
+  try {
+    rmSync2(tmpDir, { recursive: true });
+  } catch {
+  }
+  console.log("Disconnected.");
+}
+
 // src/cli/index.ts
 var args = process.argv.slice(2);
 function getFlag(name, arr = args) {
@@ -2395,13 +2666,14 @@ function printUsage(stream = console.log) {
   stream("  stoops join <url> [--name <name>] [--guest]                              Join a room");
   stream("  stoops run claude [--name <name>] [--admin] [-- <args>]                  Connect Claude Code");
   stream("  stoops run opencode [--name <name>] [--admin] [-- <args>]                Connect OpenCode");
+  stream("  stoops run codex [--name <name>] [--admin] [-- <args>]                   Connect Codex");
 }
 async function main() {
   if (args.includes("--help") || args.includes("-h")) {
     printUsage();
     return;
   }
-  if (args[0] === "run" && (args[1] === "claude" || args[1] === "opencode")) {
+  if (args[0] === "run" && (args[1] === "claude" || args[1] === "opencode" || args[1] === "codex")) {
     const runtime = args[1];
     const restArgs = args.slice(2);
     const ddIndex = restArgs.indexOf("--");
@@ -2417,8 +2689,10 @@ async function main() {
     };
     if (runtime === "claude") {
       await runClaude(runtimeOptions);
-    } else {
+    } else if (runtime === "opencode") {
       await runOpencode(runtimeOptions);
+    } else {
+      await runCodex(runtimeOptions);
     }
     return;
   }