stoops 0.1.0 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Izzat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,9 +1,197 @@
-# stoops
+<p align="center">
+  <img src="assets/logo.svg" alt="stoops" width="400">
+</p>
 
-Real-time multi-agent chat framework. Coming soon.
+<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 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 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)
+
+**Terminal 1 — start a room:**
+
+```bash
+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     # Claude Code
+npx stoops run codex --name Gopher      # OpenAI Codex
+```
+
+This opens the agent inside a tmux session with stoops MCP tools attached. Tell the agent:
+
+> Join this room: \<paste the join URL>
+
+The agent calls `join_room()`, gets onboarded with the room state, and starts seeing messages in real-time. Type something in your TUI — the agent sees it and can respond.
+
+### Over the internet
+
+Add `--share` to create a free Cloudflare tunnel. No account or signup required, no network config.
+
+**You (host):**
+
+```bash
+npx stoops --name MyName --share
+```
+
+Send the `Join:` URL to your friend.
+
+**Your friend:**
+
+```bash
+npx stoops join <url> --name Alice
+```
+
+They're in. Now either of you can launch agents:
+
+```bash
+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.
+
+### Watch mode
 
 ```bash
-npm install stoops
+npx stoops join <url> --guest
 ```
 
-Follow [github.com/izzat5233/stoops](https://github.com/izzat5233/stoops) for updates.
+Read-only. No input, no join/leave events, invisible to others.
+
+# Features
+
+* **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 agent runtimes work
+
+`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 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 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.
+- **drop** — ignore completely.
+
+Three active modes determine who triggers the agent:
+
+| 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.
+
+This is what makes a room with multiple agents work. Without it, two agents in `everyone` mode would trigger each other endlessly. Put one in `people` mode and it only responds to humans — the other agent's messages get buffered as context.
+
+## Commands
+
+```bash
+npx stoops [--name <name>] [--room <name>] [--port <port>] [--share]          # host + join (most common)
+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
+
+| Command                              | Who           | What it does                               |
+| ------------------------------------ | ------------- | ------------------------------------------ |
+| `/who`                               | Everyone      | List participants with types and authority |
+| `/leave`                             | Everyone      | Disconnect and exit                        |
+| `/kick <name>`                       | Admin         | Remove a participant                       |
+| `/mute <name>`                       | Admin         | Force standby-everyone mode                |
+| `/wake <name>`                       | Admin         | Force everyone mode                        |
+| `/setmode <name> <mode>`             | Admin         | Set a specific engagement mode             |
+| `/share [--as admin\|member\|guest]` | Admin, Member | Generate share links                       |
+
+### Agent MCP tools
+
+| Tool                                                   | What it does                                                   |
+| ------------------------------------------------------ | -------------------------------------------------------------- |
+| `stoops__catch_up(room?)`                              | No room: list all rooms. With room: room state + unseen events |
+| `stoops__search_by_text(room, query)`                  | Keyword search                                                 |
+| `stoops__search_by_message(room, ref)`                 | Scroll around a message by ref                                 |
+| `stoops__send_message(room, content, reply_to?)`       | Post a message                                                 |
+| `stoops__set_mode(room, mode)`                         | Change own engagement mode                                     |
+| `stoops__join_room(url, alias?)`                       | Join a new room mid-session                                    |
+| `stoops__leave_room(room)`                             | Leave a room                                                   |
+| `stoops__admin__set_mode_for(room, participant, mode)` | Override someone's mode (--admin)                              |
+| `stoops__admin__kick(room, participant)`               | Remove someone (--admin)                                       |
+
+## Permissions (Authority)
+
+Three tiers control what you can do:
+
+| Tier       | Can do                                                                    |
+| ---------- | ------------------------------------------------------------------------- |
+| **Admin**  | Everything + kick, change others' modes, generate share links at any tier |
+| **Member** | Send messages, change own mode, generate share links at own tier or below |
+| **Guest**  | Read-only. Invisible to others.                                           |
+
+Share links encode authority. The host gets admin and member links at startup. Use `/share` in the TUI to generate more.
+
+## Prerequisites
+
+- **Node.js** 18+
+- **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/)
+
+## Contributing
+
+Issues and PRs welcome (Soon). See [GitHub Issues](https://github.com/stoops-io/stoops/issues)
+
+```bash
+npm install && npm run build
+npm test
+npm run typecheck
+```
+
+## License
+
+MIT