Docs · Quick start

Install the hub in 5 minutes

One GitHub repo, one small file your bots update, and the board reads it. On macOS, Windows or Linux.

Where it stands: Works today, with any bot that can run a command. You need git, and Python 3.8 or newer.

Steps

Make the repo. Make a free GitHub repo for the status file, such as my-bots-status, and clone it. Public is simplest. To keep what's in it private, seal the feed: the integrations page shows how.

macOS and Linux. In Terminal, get the helper and report your first bot. It writes feed.json, commits it and pushes it, but only when something changed.

git clone https://github.com/YOU/my-bots-status.git ~/barncleuth && cd ~/barncleuth
curl -fsSLO https://barncleuth.com/hub-kit/barncleuth_status.py
python3 barncleuth_status.py my-first-bot WORKING --task "Saying hello"

Windows (PowerShell). The same three steps. Python's installer adds the py command.

git clone https://github.com/YOU/my-bots-status.git $HOME\barncleuth; cd $HOME\barncleuth
Invoke-WebRequest https://barncleuth.com/hub-kit/barncleuth_status.py -OutFile barncleuth_status.py
py barncleuth_status.py my-first-bot WORKING --task "Saying hello"

Point the board at it. On your board, open the menu, then Load a status file, and paste the file's raw address.
```
https://raw.githubusercontent.com/YOU/my-bots-status/main/feed.json
```
Report from your bots. Have each bot run the helper when it starts, finishes or gets stuck: WORKING, DONE, HOLD when it's waiting for you, or BLOCKED with a reason. The integrations page has the lines for Claude Code, OpenClaw, n8n, Python, MCP agents and Grok.
```
python3 barncleuth_status.py publisher BLOCKED --blocker "YouTube upload quota hit"
python3 barncleuth_status.py publisher DONE --post-url https://youtu.be/...
```
Approvals and pause switches: control-sync.sh. Optional. control-sync.sh is the hub's side of approvals and pause switches. Run it about once a minute. It reads your decisions and pause switches from the board, writes them into control/ for your bots to read (paused.txt, low_usage.txt, and one file per decision in control/decisions/), tells a waiting bot if you set HUB_WAKE_CMD, and confirms delivery so the board can say the bot was told. WORKSTATION_HUB_KEY comes from the board's Team tab, under Hub connection. It's a bash script, so on Windows run it in Git Bash or WSL.
```
curl -fsSLO https://barncleuth.com/hub-kit/control-sync.sh && chmod +x control-sync.sh
# Every minute, with cron (crontab -e):
* * * * * cd ~/barncleuth && WORKSTATION_URL=https://your-board WORKSTATION_HUB_KEY=... ./control-sync.sh
```

What it sends

Only what you write in feed.json, in your own GitHub repo. The board reads it from there. No bot keys or passwords ever go in it.

How it's tested

The helper's own tests run in Python 3.12 under WebAssembly. We haven't yet run these exact commands on a Mac, a Windows PC and a Linux machine.

See your own team on one board

Look around the demo first. There's nothing to set up and no signup.

Open the demo