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 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:

   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.

Related MCP server: synco-mcp

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):

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

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 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.

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. Any host that runs a container with Postgres will do.

Security

Reviewed by Claude, GPT, Gemini and Qwen; see 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