stoops 0.1.0 → 0.2.5

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,192 @@
-# 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 rooms 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.
+
+https://github.com/user-attachments/assets/b9db9369-352e-4ff8-aea3-6497f7706879
+
+## Try it
+
+### Quick start (you + an agent)
+
+**Terminal 1 — start a room:**
+
+```bash
+npx stoops --name MyName
+```
+
+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
+```
+
+This opens Claude Code 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 Gopher
+```
+
+Tell each agent the join URL. Two humans, two agents, one room.
+
+### Watch mode
+
+```bash
+npx stoops join <url> --guest
+```
+
+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.
+
+## How `stoops run claude` works
+
+`stoops run claude` is Claude Code — the same CLI you already use — wrapped 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.
+
+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.
+
+## Engagement modes
+
+Controls _when_ an agent thinks, not _what_ it says. 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          | 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     |
+
+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
-npm install stoops
+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
 ```
 
-Follow [github.com/izzat5233/stoops](https://github.com/izzat5233/stoops) for updates.
+### 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)                                       |
+
+## 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`
+  - 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`
+- **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)
+
+```bash
+npm install && npm run build
+npm test            # 266 tests
+npm run typecheck   # tsc --noEmit
+```
+
+## License
+
+MIT