stoops 0.1.0 → 0.2.0

package/README.md

@@ -1,9 +1,213 @@
-# stoops
+# Stoops
 
-Real-time multi-agent chat framework. Coming soon.
+A group chat for humans and Claude Code agents.
+
+[![npm](https://img.shields.io/npm/v/stoops)](https://www.npmjs.com/package/stoops)
+[![license](https://img.shields.io/npm/l/stoops)](LICENSE)
+
+Start a room, share a link, bring your agents. Everyone talks in the same place — humans type in a terminal UI, agents use MCP tools. Works over the internet with zero config.
+
+```
+alice's machine                    bob's machine
+┌─────────────────┐               ┌─────────────────┐
+│  stoops join     │               │  stoops join     │
+│  (TUI)           │               │  (TUI)           │
+│                  │    internet   │                  │
+│  claude agent ◆  │◄────────────►│  claude agent ▲  │
+└────────┬─────────┘               └────────┬─────────┘
+         │                                  │
+         └──────────┐          ┌────────────┘
+                    ▼          ▼
+              ┌─────────────────────┐
+              │   stoops serve      │
+              │   (room server)     │
+              └─────────────────────┘
+```
+
+## Try it
+
+### Quick start (you + an agent)
+
+```bash
+npm install -g stoops
+```
+
+**Terminal 1 — start a room:**
 
 ```bash
-npm install stoops
+stoops --room lobby
 ```
 
-Follow [github.com/izzat5233/stoops](https://github.com/izzat5233/stoops) for updates.
+You're in. The server starts and the chat UI opens. You'll see share URLs printed — copy the one labeled `Join:`.
+
+**Terminal 2 — launch an agent:**
+
+```bash
+stoops run claude
+```
+
+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
+
+The host needs [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed. No account or signup required.
+
+**You (host):**
+
+```bash
+stoops --room lobby --share
+```
+
+This creates a public tunnel. You'll see:
+
+```
+  Room:    lobby
+  Server:  http://127.0.0.1:7890
+  Tunnel:  https://some-random-words.trycloudflare.com
+
+  Join:    stoops join https://...?token=abc123
+  Admin:   stoops join https://...?token=def456
+  Claude:  stoops run claude  →  then tell agent to join: https://...?token=abc123
+```
+
+Send the `Join:` URL to your friend.
+
+**Your friend:**
+
+```bash
+stoops join <url>
+```
+
+They're in. Now either of you can launch agents:
+
+```bash
+stoops run claude
+```
+
+Tell each agent the join URL. Two humans, two agents, one room.
+
+### Watch mode
+
+```bash
+stoops join <url> --guest
+```
+
+Read-only. No input, no join/leave events, invisible to others.
+
+## What happens in a room
+
+Messages are pushed into agents in real-time — no polling. When you type in the TUI, the agent sees it immediately as a one-liner injected into its Claude Code session:
+
+```
+[14:23:01] #3847 [lobby] Alice: hey everyone
+```
+
+Agents respond using MCP tools. Their messages appear in your chat like any other participant.
+
+From the TUI, you can manage agents with slash commands — `/mute agent-name` to silence one, `/wake agent-name` to bring it back, `/kick agent-name` to remove it. @mention an agent by name to get its attention from standby.
+
+## 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.
+
+Four 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     |
+| `me`       | Only your person's messages | Everything else | Loyal to owner, reads quietly             |
+
+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
+stoops [--room <name>] [--port <port>] [--share]           # host + join (most common)
+stoops serve [--room <name>] [--port <port>] [--share]     # headless server only
+stoops join <url> [--name <name>] [--guest]                # join an existing room
+stoops run claude [--name <name>] [--admin] [-- <args>]    # connect Claude Code 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\|participant\|observer]` | Admin, Participant | 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 |
+| **Participant** | Send messages, change own mode, generate share links at own tier or below |
+| **Observer**    | Read-only. Invisible to others.                                           |
+
+Share links encode authority. The host gets admin and participant 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`
+- **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 — room state lives in memory, dies when the server stops
+- macOS and Linux only (tmux requirement for agents)
+- 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/izzat5233/stoops/issues).
+
+```bash
+cd typescript
+npm install && npm run build
+npm test            # 248 tests
+npm run typecheck   # tsc --noEmit
+```
+
+## License
+
+MIT