Set it up

One command does everything, and it works the same on Windows, macOS and Linux. Pick whichever of these two suits you.

Let an AI tool do it

Paste one block into Claude Code, Codex, Cursor, Gemini CLI, Cowork or anything similar. It checks your machine, proves the install works, and asks you three questions.

About five minutes → No AI tool needed

Do it yourself

Three steps. Every one is a command you copy and paste — you do not need to know any Python.

About fifteen minutes →

Whichever you pick, do the demo first. There is a fake Tabbycat built in, so you can run all three tools before you have a tab address, a token, or permission from anyone. If it works there, any later problem is about your tournament and not about your laptop — which is a much easier thing to fix.

Let an AI tool do it

Any coding assistant that can run commands will do this. Copy the block and paste it in:

Set up the Tabbycat Adjcore Toolkit for my tournament.

It is a Python project. Do this and nothing else:

1. Clone https://github.com/REPLACE_ME/tabbycat-adjcore-toolkit and cd into it.
2. Run:  python3 run.py check      — tell me anything it says is missing.
3. Run:  python3 run.py demo       — this needs no tournament and no login.
                                     Show me the result. If it fails, stop and
                                     fix my install before going further.
4. Run:  python3 run.py setup      — it asks me three things. Let ME answer
                                     them; do not invent a tab address, a slug
                                     or a token. It prints my tournament's
                                     round and team counts at the end: show me
                                     those and ask if they look right.
5. Then tell me these three commands and what each does, and stop:
       python3 run.py testers
       python3 run.py fold
       python3 run.py feedback

Rules: the toolkit only ever reads my tab and cannot write to it, so if a step
looks like it needs to change something in Tabbycat, stop and tell me. Do not
publish anything. Do not run the feedback tool past the point where it asks me
to read the summaries.

That works in Claude Code, Claude Cowork, OpenAI Codex, Cursor, Windsurf, Gemini CLI, Aider, GitHub Copilot's agent mode — anything that can run a terminal command and read what comes back. Nothing in it is specific to one tool.

If you use Claude Code there is a shorter way: clone the repo, run claude inside it, and type /setup. The repo ships that as a skill, so it already knows the order things happen in.

Two things the prompt deliberately tells it not to do, and you should keep them: do not let it make up your tab address or token, and do not let it publish judge feedback without you reading it. Both of those are yours.

Do it yourself — three steps

The commands below change to match.

Get it, and check your machine
```
git clone https://github.com/REPLACE_ME/tabbycat-adjcore-toolkit
cd tabbycat-adjcore-toolkit
python3 -m pip install requests
python3 run.py check
```
No git? Download the zip, unzip it, and cd into the folder instead.
Open PowerShell — press the Start key, type powershell, press enter.
```
git clone https://github.com/REPLACE_ME/tabbycat-adjcore-toolkit
cd tabbycat-adjcore-toolkit
python -m pip install requests
python run.py check
```
No git or no python? Get Python from python.org (tick Add Python to PATH in the installer), and download the zip instead of cloning. You do not need WSL.
check tells you in plain words whether anything is missing, and the one command that fixes it.
Try it on a tournament that does not exist
```
python3 run.py demo
```
```
python run.py demo
```
This runs all three tools against three invented tournaments. No tab, no sign-in, nothing leaves your machine. It takes about a minute and it is the cheapest possible way to find out whether anything is wrong.
Point it at your tournament
```
python3 run.py setup
```
```
python run.py setup
```
It asks three things:
- Your tab's web address — everything before the tournament name, like https://yourtournament.calicotab.com
- The tournament's bit of the address — if your tab is at https://x.calicotab.com/openx26/ this is openx26
- Your API token — sign in to your tab in a browser and open Change Password on the home page. It is on that page. (More about that, including what to tell your tab director.)
Then it reads your tab and prints your round count, team count, judge count and break categories. Check those look like your tournament. If they do not, it is almost always the slug — and you have found that out in ten seconds rather than an hour.

That is the setup. Nothing about how many rounds you have, your break categories, your panel sizes or your format — all of that is read from your tab every time a tool runs.

Then, the three tools

python3 run.py testers     # who has been watched, and who still needs to be
python3 run.py fold        # builds the public page and opens it for you to check
python3 run.py fold --publish
python3 run.py feedback    # consolidated judge feedback, with a stop for you to read it

python run.py testers      # who has been watched, and who still needs to be
python run.py fold         # builds the public page and opens it for you to check
python run.py fold --publish
python run.py feedback     # consolidated judge feedback, with a stop for you to read it

Tool	When to run it	What to know
Tester tracking	After each draw goes out	Opens in your browser. Go to the Testing tab.
The fold	Whenever you want the public page current	`fold` builds and shows you. `fold --publish` puts it online. It refuses to publish a page that fails its own checks.
Judge feedback	Once, at the end	It stops after writing the summaries and tells you to read them. That stop is the point.

Opening a new terminal window? Your token is in a file called .env and each new window needs it loaded.

set -a; . .env; set +a

Get-Content .env | ForEach-Object { if ($_ -match '^export (\w+)=(.*)$') { [Environment]::SetEnvironmentVariable($Matches[1], $Matches[2]) } }

python3 run.py check will tell you if you have forgotten.

If something goes wrong

Run run.py check first — it catches most of it and says what to do. Otherwise:

What you see	What it is
`python3: command not found` (or `python`)	On Windows use `python`, not `python3` — and make sure you ticked Add Python to PATH when installing.
`No module named requests`	`python3 -m pip install requests`
`No way to sign in to the tab was found`	`.env` is not loaded in this window — see the box above.
The numbers after `setup` are not your tournament	The slug. You are reading a different tournament on the same host.
`403 Forbidden`	You signed in, but the account is not on the tab side. You need adjudication core or tabulation access — why that is unavoidable.
The fold refuses to publish	Working as intended. It stops rather than publishing when one of its checks fails, and the message names the check.
A judge has no feedback summary	Either nobody wrote about them, or their drafts failed the content rules four times. Run `run.py feedback --step write` again; it only does the missing ones.
Anything else	Open an issue with what you ran and what it printed. Not your token.

When your tournament is over, delete the feedback/data folder. It holds every adjudicator's private link, and those are credentials — why.

What run.py actually does, and doing it without run.py

Nothing, beyond calling the same modules directly and printing more helpfully. It exists because the direct route means changing directory, knowing which script comes next, and running shell scripts that do not exist on Windows — none of which is the interesting part.

run.py check      prerequisites, config and whether .env is loaded
run.py demo       demo/verify.py
run.py setup      writes tournament.json and .env, then reads your tab once
run.py testers    tester-tracking/pull.py, then server.py
run.py fold       fold/build.py, then fold/tests/test_gate.py, then opens dist/
run.py feedback   feedback/{pull,bundle,summarise,build}.py + the gate, in order,
                  stopping after summarise so a person reads the output

Every one of those is runnable on its own, and the shell equivalents (fold/refresh, feedback/refresh, tester-tracking/start) are still there for anyone who prefers them. They are POSIX shell, so on Windows use run.py.

Publishing goes through npx — Cloudflare Pages by default, Netlify and surge also supported by one word in tournament.json. That is the only step that needs Node.

Next: what tester tracking actually does →