Metadata-Version: 2.4
Name: promptparty
Version: 0.1.2
Summary: Cadence sync for teams agent-coding in the same room — one dashboard that says when to PROMPT and when to TALK.
Project-URL: Homepage, https://github.com/moudrkat/promptparty
Project-URL: Issues, https://github.com/moudrkat/promptparty/issues
Author-email: k.moudra@seznam.cz
License: MIT
License-File: LICENSE
Keywords: agentic-coding,claude,claude-code,collaboration,hackathon,hooks,llm,pair-programming
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Description-Content-Type: text/markdown

# promptparty 🎉

![promptparty demo — the dashboard flipping between TALK and PROMPT](https://raw.githubusercontent.com/moudrkat/promptparty/main/docs/demo.gif)

**Cadence sync for teams agent-coding in the same room.** One shared dashboard
that tells everyone when it's time to **⌨️ PROMPT** and when it's time to
**🗣️ TALK** — because the worst part of group agentic coding is everyone
heads-down at different moments, waiting on each other, and the conversation
dying.

The rhythm promptparty gives you:

1. **⌨️ PROMPT** — someone's agent finished (or needs a permission). Read the
   output, fire the next prompt.
2. **🗣️ TALK** — *all* agents are generating. Hands off the keyboard: discuss
   what's coming, plan the next move, actually talk to each other.
3. Agents finish → the dashboard flips back to PROMPT (with an optional chime).

Everyone keeps their **own terminal, own Claude Code session, own model** —
promptparty never calls a model and needs **no API key**. It only watches the
states.

## Quickstart (60 seconds)

**One person** starts the server and opens a room (put it on a big screen or a
spare browser tab):

```bash
uvx promptparty          # or: pipx install promptparty && promptparty
```

**Each teammate** runs one command inside the project they're coding in:

```bash
uvx promptparty hooks --server http://192.168.1.20:8765 --room a1b2c3 --name Katka
```

(The dashboard's ⚙️ panel shows this exact command with your room pre-filled.)
That installs [Claude Code hooks](https://code.claude.com/docs) into
`./.claude/settings.json` that report automatically:

| you do | dashboard shows |
|---|---|
| submit a prompt (`UserPromptSubmit`) | 🤖 agent running — *free to talk* |
| agent finishes its turn (`Stop`) | ✅ agent done — *read & prompt!* |
| agent asks for permission (`Notification`) | 🙋 needs a decision |

Restart your Claude Code session (or reload hooks) and you're live.

### Team setup — commit it once, everyone's in

Instead of per-person installs, one person can write a **shared, committable**
config into the repo:

```bash
uvx promptparty hooks --shared --server http://SERVER:8765 --room a1b2c3
git add .claude/settings.json && git commit -m "promptparty hooks"
```

Teammates' names are resolved at runtime from `$PROMPTPARTY_NAME` (falling
back to `$USER`), and the server/room can be overridden with
`$PROMPTPARTY_SERVER` / `$PROMPTPARTY_ROOM` — so after `git pull`, everyone is
hooked up with zero setup.

### Not using Claude Code?

Any tool can report with one request — wire it into whatever hooks your tool
has, or an alias:

```bash
curl -X POST http://SERVER:8765/api/ROOM/event \
     -H 'content-type: application/json' \
     -d '{"name":"Katka","state":"generating"}'
# states: prompting | generating | ready | blocked | away
```

There are also manual buttons at the bottom of the dashboard.

## What you get

- 🚦 A giant phase banner: **TALK** (all agents cooking) / **PROMPT**
  (with *who* the room is waiting on).
- 🃏 A card per person: state, model, how long they've been in it. Blocked
  agents pulse red so permission prompts stop rotting unnoticed.
- 🔔 Optional chime on phase flips — you don't even need the screen in view.
- 📊 Session stats: talk time vs prompt time and total prompts fired.
  (Great post-hackathon bragging material.)
- 🧹 Zero config, zero database, zero API keys. Rooms live in memory.

## How it works

A single FastAPI process keeps per-room state and pushes it to dashboards over
WebSockets. Hook reports are plain HTTP POSTs. The phase rule is one line:

> if every non-away member's agent is generating → **TALK**, otherwise → **PROMPT**.

That's the whole trick. It works because agent turns are long enough (tens of
seconds to minutes) that "all agents running" is a genuine conversational
window.

## Options

```
promptparty [serve] [--port 8765] [--host 0.0.0.0] [--min-talk 120]
promptparty hooks --server URL --room SLUG --name YOU [--settings PATH]
promptparty hooks --remove [--settings PATH]
```

Playing from different networks? Put the server behind any tunnel
(`ngrok http 8765`, `cloudflared tunnel --url http://localhost:8765`).

## Roadmap

- [ ] `PreCompact` / `SubagentStop` hook nuances (long multi-agent turns)
- [ ] Per-room history graph (talk/prompt timeline you can screenshot)
- [x] Minimum TALK window (`--min-talk`, default 120 s) — an early-finished agent waits out the window
- [ ] Full pomodoro mode: enforced fixed windows
- [ ] Adapters for aider / codex / opencode hooks out of the box

PRs welcome — this was born at a hackathon and stays intentionally tiny: one
Python file of server, one HTML file of dashboard, no build step.

## Security notes

- Anyone with the room URL can view and post states. It's presence data, not
  code — but run it on a network you trust.
- Rooms are in-memory and vanish on restart.

## License

MIT © [moudrkat](https://github.com/moudrkat)
