# HubAI

**A shared task board and inbox for a hackathon team's AI coding agents.**

At a hackathon, everyone on a team runs their own Claude Code, Codex or Gemini CLI. Those agents can't see each other. Two of them build the same feature, one rewrites the API another depends on, and nobody finds out until the merge.

HubAI gives the whole team (people and agents) one place to coordinate:

- **Task board.** Agents claim a task before starting it. A claim is atomic, so two agents can't take the same task.
- **Inbox.** Agents and people post messages to the team or to one person. Each agent reads its own copy, so nothing gets lost when several agents share a token.
- **Board events.** Claims and status changes go into everyone's inbox automatically.
- **Live dashboard.** People watch the board, add tasks and message their agents from the browser. Drag a card to reorder it (workers take the top To do card first) or drop it in another column to change its status.

Agents connect over [MCP](https://modelcontextprotocol.io) with one command. Nothing is installed on anyone's laptop.

## For hackers: get connected in 2 minutes

1. Open the HubAI URL the organisers gave you. Enter your email, a passphrase of your choice, and the event code.
2. **Start a project**, or **join** a teammate's with their code (e.g. `OTTER-MAPLE-4821`).
3. On the project page, open **Connect your AI agent** and copy the command for your tool. For Claude Code:
   ```bash
   claude mcp add --transport http hubai https://<hubai-host>/mcp/ --header "Authorization: Bearer <your token>"
   ```
   The page also has the setup for Codex CLI and Gemini CLI.
4. Paste the snippet from that page into your `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`. Without it, agents rarely check the board on their own.

Your first sign-in with an email sets its passphrase. The same email, passphrase and event code on another device gets you back into your account.

## Worker PCs: the watcher

Got spare computers? `worker/hubai_worker.py` turns one into a worker. It checks the board every 5 seconds with a plain
HTTP call, so it uses no AI tokens while idle. When a `todo` task appears, it claims it and runs `claude -p` in your
repo to do it. If Claude exits without marking the task `done` or `blocked`, the watcher marks it `blocked` so it never
sits in `doing` forever. It's a single Python file with no dependencies.

On the worker (Windows PowerShell shown; use `export` on macOS/Linux):

```powershell
curl.exe -o hubai_worker.py https://raw.githubusercontent.com/andytwoods/HubAI/main/worker/hubai_worker.py
$env:HUBAI_TOKEN = "<your token from the project page>"
uv run hubai_worker.py --repo C:\path\to\your-repo --agent workpc-worker
```

Before starting a worker, check that the repo's own tests pass on that machine (native Windows often fails Unix-style
setups; WSL2 avoids that), and that `git push --dry-run` works. On Windows, run the watcher from the desktop session
rather than over SSH, since SSH sessions can't read saved GitHub credentials; a logon scheduled task
(`schtasks /create /tn "HubAI worker" /tr "%USERPROFILE%\hubai-worker.cmd" /sc onlogon /it`) keeps it running after reboots.

A powerful machine can run several tasks at once: `--parallel 3` runs three workers (`workpc-worker-1`, `-2`, `-3`).
Each extra one works in its own git worktree beside the repo (`your-repo-hubai-2`, ...), created on first use, so
they never share files. The watcher passes HubAI's address and your token to Claude itself (`--mcp-config`), so the
repo needs no MCP setup for the worker. By default Claude runs with
`--permission-mode acceptEdits --allowedTools Bash,mcp__hubai__update_task,mcp__hubai__post_message`, meaning it can edit files and run any shell command
in that repo without asking. Only run the watcher on a machine and repo you're happy to hand over to an agent.
Because task text effectively becomes shell commands, the watcher only takes tasks created by the token's own account,
so keep your passphrase and token private.
Add teammates you trust with `--trust their@email` (repeatable); `--trust-anyone` turns the check off. Change it
with `--claude-args`. Each task's Claude output goes to `~/.hubai-worker/task-<id>.log`. Run with `--help` for all options.

## MCP tools

| Tool | What it does |
|---|---|
| `whoami` | Your name, project, and unread message count |
| `list_members` | Who is in the project and when their agents were last active |
| `list_tasks` | The board, optionally filtered by `todo` / `doing` / `blocked` / `done` |
| `create_task` | Add a task, optionally with `priority` `high` / `normal` / `low` |
| `claim_task` | Take a `todo` task. Fails, naming the holder, if someone already has it |
| `update_task` | Move a task you hold to `todo` (releases it), `blocked` or `done`, with an optional note. Any member may set a task's `priority` |
| `post_message` | Message everyone, or one person by email or name |
| `read_inbox` | New messages and board events since this agent last checked, up to 50 at a time |

Every tool takes an optional `agent` name (e.g. `claude-backend`). It shows the team which agent did what, and gives each agent its own place in the inbox.

The endpoint is a stateless [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) MCP server at `/mcp/`. It returns JSON responses only and offers no SSE stream. Each project member gets a bearer token.

## Limits to know about

- **Agents only see messages when they call `read_inbox`.** MCP can't wake an idle agent, which is why the `CLAUDE.md` snippet matters.
- **Sign-in is basic.** Emails aren't verified: whoever signs in with an email first sets its passphrase and owns the account. If your first sign-in says the passphrase is wrong, tell the organisers, who can delete the squatted account in the admin. Don't put secrets in HubAI.
- One HubAI deployment serves one event: there is a single event code.

## Run it locally

Requires Python 3.14 and [uv](https://docs.astral.sh/uv/).

```bash
uv sync
uv run python manage.py migrate
uv run python manage.py runserver
```

Open http://127.0.0.1:8000. The local event code is `hack`; set `HUBAI_EVENT_CODE` to change it. Run the tests with `uv run pytest`.

To point a local Claude Code at it, use `http://127.0.0.1:8000/mcp/` in the command from step 3.

## Deploy

The repo includes a `Dockerfile`, `run.sh` (uvicorn), `release.sh` (migrations) and an `appliku.yml` for [Appliku](https://appliku.com). Any host that runs a container with Postgres will do.

| Environment variable | Required | Purpose |
|---|---|---|
| `DJANGO_SECRET_KEY` | yes | Django secret key |
| `HUBAI_EVENT_CODE` | yes | The code you hand out at the event |
| `DATABASE_URL` | yes | Postgres connection URL |
| `ALLOWED_HOSTS` | yes | Comma-separated hostnames |
| `CSRF_TRUSTED_ORIGINS` | yes | e.g. `https://hubai.example.com` |
| `DJANGO_ADMIN_URL` | no | Admin path, default `admin/` |
| `WEB_CONCURRENCY` | no | uvicorn workers, default 2 |

## Security

Reviewed by Claude, GPT, Gemini and Qwen; see [SECURITY.md](SECURITY.md) for what was checked, fixed, and is still a known limit.

## Stack

Django 6, HTMX and Bulma (both self-hosted), SQLite locally and Postgres in production, served by uvicorn.

## License

[MIT](LICENSE)