Metadata-Version: 2.5
Name: team-table
Version: 0.2.1
Summary: Multi-model AI team coordination via MCP — the missing coordination layer for multi-agent, multi-provider AI systems
Project-URL: Homepage, https://github.com/Brickmii/team-table
Project-URL: Repository, https://github.com/Brickmii/team-table
Project-URL: Issues, https://github.com/Brickmii/team-table/issues
Author: Brickmii, Claude (Anthropic), Codex (OpenAI)
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: ai,coordination,llm,mcp,multi-agent,sqlite,team
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: mcp<2,>=1.28.1
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: sse-starlette>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# Team Table

Multi-model AI team coordination via MCP (Model Context Protocol).

An MCP server that lets multiple AI instances discover each other, coordinate tasks, and communicate through a shared SQLite database.

## Quick Start

```bash
pip install team-table
```

For development:

```bash
pip install -e ".[dev]"
```

### Register as MCP server in Claude Code

Windows:

```bash
claude mcp add --transport stdio --scope user team-table -- \
  path/to/.venv/Scripts/python.exe -m team_table.server
```

macOS/Linux:

```bash
claude mcp add --transport stdio --scope user team-table -- \
  path/to/.venv/bin/python -m team_table.server
```

### Register as MCP server in Codex

Windows:

```bash
codex mcp add --transport stdio --scope user team-table -- \
  path/to/.venv/Scripts/python.exe -m team_table.server
```

macOS/Linux:

```bash
codex mcp add --transport stdio --scope user team-table -- \
  path/to/.venv/bin/python -m team_table.server
```

## Network Mode (LAN)

Run the server over the network so other machines can connect:

```bash
# Start the server in SSE mode (or use streamable-http)
TEAM_TABLE_TRANSPORT=sse python -m team_table.server
```

From another PC on the LAN, register the remote server:

```bash
claude mcp add --transport sse team-table http://<host-ip>:8741/sse
```

From Codex on another PC on the LAN, register the same remote server:

```bash
codex mcp add --transport sse team-table http://<host-ip>:8741/sse
```

### Environment Variables

| Variable | Default | Description |
|---|---|---|
| `TEAM_TABLE_DB` | `~/.team-table/team_table.db` | Path to the SQLite database |
| `TEAM_TABLE_TRANSPORT` | `stdio` | Transport mode: `stdio`, `sse`, or `streamable-http` |
| `TEAM_TABLE_HOST` | `127.0.0.1` | Bind address for network transports (`0.0.0.0` to serve the LAN) |
| `TEAM_TABLE_PORT` | `8741` | Listen port for network transports |
| `TEAM_TABLE_REQUIRE_TOKENS` | `true` | Require auth tokens for tool calls and SSE |
| `TEAM_TABLE_ADMINS` | (none) | Comma-separated names allowed to register as `admin` or `lead` |
| `TEAM_TABLE_ALLOW_INSECURE` | `false` | Allow a network transport with tokens off (anyone on the network could act as anyone) |

## Architecture

Each Claude Code instance spawns its own STDIO MCP server process. All processes share one SQLite database (`~/.team-table/team_table.db`) using WAL mode for concurrent access. Alternatively, a single server can be run in network mode (SSE or streamable-http) to serve multiple clients over the LAN.

## Tools (18)

- **Registration**: `register`, `deregister`, `list_members`, `heartbeat`
- **Messaging**: `send_message`, `get_messages`, `broadcast`, `delete_message`, `archive_message`, `clear_inbox`, `purge_messages`
- **Task Board**: `create_task`, `list_tasks`, `claim_task`, `update_task`
- **Shared Context**: `share_context`, `get_shared_context`
- **Audit**: `get_audit_log`

### Auth Tokens

`register` returns a per-agent token. All tool calls (and the SSE event stream) require
the token unless `TEAM_TABLE_REQUIRE_TOKENS=false`. Re-registering a name that is already at the
table needs that name's current token, so nobody can take over an active agent.

### Roles

`admin` and `lead` can't be self-assigned through `register`. The operator — whoever has the
database file — grants them:

```bash
python -m team_table.admin list
python -m team_table.admin grant claude-opus lead
python -m team_table.admin revoke-tokens some-agent
```

Names listed in `TEAM_TABLE_ADMINS` may register directly with a privileged role.

### Network security

Network mode speaks plain HTTP: tokens and messages cross the network unencrypted. Use it on a
trusted LAN, or put it behind TLS (a reverse proxy, or an SSH tunnel). With tokens off, a network
transport refuses to start unless `TEAM_TABLE_ALLOW_INSECURE=true`. The database is created
readable by its owner only.

### Shared context keys

Keys are a shared board anyone at the table can update, and every overwrite records who held the
key before. A key named `owner/...` (for example `alice/plan`) belongs to that member: only they,
or an admin/lead, can change it.

### Broadcasts

Archiving or deleting a broadcast hides it from your own inbox. Only its sender, or an admin/lead,
removes it for everyone.

### Message Management

Messages can be archived (soft-delete + mark read), deleted (soft-delete), or purged (hard-delete, admin/lead only). `clear_inbox` supports bulk archival with optional date and sender filters. Archived messages are excluded from inbox queries and unread counts by default.

### SSE Push Notifications

In network mode, agents can subscribe to real-time events at `GET /events/{agent_name}`. The server pushes notifications for new messages, broadcasts, and task assignments. A 30-second heartbeat keeps connections alive. The poll daemon remains available as a fallback for STDIO transport.

### Audit Log

All state-changing actions (registration, messaging, task updates, context sharing) are recorded in an append-only audit log. Query with `get_audit_log` using optional agent, action, and date filters.

### Security

- Input validation on all tool parameters (agent names, messages, task fields)
- Rate limiting: 30 messages per 60-second window per sender
- Role-based access control: `admin`, `lead`, `coder`, `reviewer`, `designer`, `tester`, `agent`
- Privileged operations (purge, delete others' messages) restricted to admin/lead roles

## Poll Daemon (Auto-Messaging)

By default, agents must manually check for messages. The poll daemon automates this — it monitors an agent's inbox and auto-responds, only escalating to the user when needed.

### How It Works

1. Polls the database every 30 seconds for unread messages
2. Sends an acknowledgement reply to each incoming message
3. **Escalates to the user** (stops auto-replying) when:
   - The total auto-reply count exceeds the limit (default: 13)
   - A message contains a question or decision request (e.g. "should we…?", "please approve", "what do you think")
4. Notifies the sender with an `[AUTO]` message explaining the escalation

### Usage

```bash
# Start polling for an agent (default: 30s interval, 13 message max)
python scripts/poll_daemon.py claude-opus

# Custom interval and message limit
python scripts/poll_daemon.py claude-opus --interval 15 --max-messages 13

# With a custom database path
TEAM_TABLE_DB=/path/to/db python scripts/poll_daemon.py claude-opus
```

### Safety

- **Hard message cap** prevents runaway agent-to-agent loops
- **Question detection** forces human review on decisions
- **Pull-based** — no exposed network endpoints
- **Graceful shutdown** via Ctrl-C or SIGTERM
- All activity is logged to the terminal with timestamps

## Development

```bash
pytest          # run tests
ruff check .    # lint
```

### Recommended Workflow (PyCharm + OAuth)

For day-to-day development, use a JetBrains-first flow:

1. Run and debug code/tests in PyCharm.
2. Use browser-based OAuth sign-in from PyCharm for provider access.
3. Keep `team-table` auth-token enforcement enabled (`TEAM_TABLE_REQUIRE_TOKENS=true`).
4. Treat each agent as a distinct identity with its own token and role.

Token guidance for the table process:

- Register each agent once, capture its returned token, and store it in IDE run configs or environment variables.
- Rotate/revoke tokens when an agent is repurposed or a workstation changes ownership.
- Never share one token across multiple agents; tokens are agent-scoped.

Future multi-agent expansion:

- Add agents incrementally (coding, review, QA, design, ops) with explicit roles and capabilities.
- Keep one shared database (`TEAM_TABLE_DB`) for coordination and audit history.
- Use network mode (`sse` or `streamable-http`) when agents run across multiple machines.

## License

GPL-3.0-or-later
