# Tutti *Tutti* (music): everyone plays together. Tutti lets one household share its AI subscriptions, local models, computers and Android devices for software work, without anyone stepping on anyone else. > **Status: 0.17.x** (see [CHANGELOG.md](CHANGELOG.md) and the [releases](https://github.com/ventura8/Tutti/releases)). > Linux first; the installer also covers macOS, WSL and Windows. **Licence:** MIT. ## What Tutti does, in plain words - **One main agent, many helpers.** A capable agent (Claude Code, or any other, [docs/CONDUCT.md](docs/CONDUCT.md)) plans and reviews; bounded tasks go to cheaper workers (other CLI agents, local models), each in its own worktree, and every diff is reviewed and checked before it lands ([docs/WORKERS.md](docs/WORKERS.md)). - **Accounts and usage pacing.** Tutti reads how much of each subscription is used, paces work so quota lasts until each reset, and moves work to an account or model with room when one runs out. Local workers become available again when their work ends ([docs/USAGE-PACING.md](docs/USAGE-PACING.md)). - **The best local AI in the house.** Tutti's own AI always uses the best free model on any household machine, falls back online only within pacing, and briefly goes first on that model; other work waits a few seconds and loses nothing ([docs/FLEET.md](docs/FLEET.md), [docs/TELEMETRY.md](docs/TELEMETRY.md#ai-assist)). - **Machines that stay yours.** Tests and builds run on other machines through slots and leases. Each machine can have limited hours and a night mode; Android devices can have blocked hours; work pauses when someone is at the keyboard, and a machine's yield flag gives it back at once. Machines can take Cast roles, and work follows devices when they move ([docs/MACHINES.md](docs/MACHINES.md), [docs/DEVICES.md](docs/DEVICES.md), [docs/DISPATCH.md](docs/DISPATCH.md), [docs/PRESENCE.md](docs/PRESENCE.md)). Device leases accept options before `--` and preserve the command and its own options after it. - **A main and a backup main.** One always-on machine runs Tutti; a backup takes over if it goes down and hands back when it returns, never both at once ([docs/FAILOVER.md](docs/FAILOVER.md), [docs/MOVE.md](docs/MOVE.md)). - **The unblocker and the needs-input queue.** Stuck or failing work is retried with a fix, rebased or rerun by Tutti itself; only real decisions reach *Needs you* ([docs/NEEDS.md](docs/NEEDS.md), [docs/AUTOPILOT.md](docs/AUTOPILOT.md)). - **It looks after itself.** Self-heal installs declared dependencies, restarts services, cleans old temp folders and applies updates; routine clean-ups are counted apart from real repairs ([docs/SELFHEAL.md](docs/SELFHEAL.md)). - **GitHub connection.** Connect GitHub once from the dashboard ([docs/GITHUB.md](docs/GITHUB.md)). - **Dashboard and chat.** A web dashboard on your LAN or VPN only, never on the public internet, with Google sign-in and roles. It opens on **Chat** (ask "why is the NUC idle?" or queue work), then Dashboard (usage, jobs, needs), **Machines** cards (one per physical computer, with WSL and desktop environments nested under it; slots busy, held back or free, and why) and Settings. An **Admin** tab is coming ([docs/DASHBOARD.md](docs/DASHBOARD.md), [docs/CHAT.md](docs/CHAT.md), [docs/NETWORK.md](docs/NETWORK.md), [docs/AUTH.md](docs/AUTH.md)). Automatic page updates and Settings restarts protect this tab's unsent Chat work and active answers. Cooperating Chat storage writers serialize on supported POSIX hosts; this does not enable simultaneous dashboard engines. Interrupted answers that may have started work ask you to check its status before a new request. Job reports and logs in Chat are restricted to admins, including when a model requests them. ## Install One line, then sign in. **Linux, WSL, macOS:** ```bash curl -fsSLo tutti-bootstrap.sh https://github.com/ventura8/Tutti/releases/latest/download/bootstrap.sh && echo "17ccfd80f790fb48fc1642870b58e70a396a473bee88d279ba7ab6256eb56635 tutti-bootstrap.sh" | (sha256sum -c - || shasum -a 256 -c -) && bash tutti-bootstrap.sh ``` **Windows (PowerShell):** ```powershell irm https://github.com/ventura8/Tutti/releases/latest/download/bootstrap.ps1 -OutFile tutti-bootstrap.ps1; if ((Get-FileHash tutti-bootstrap.ps1).Hash -eq 'CAACFE5D2E3F84B59D62263D5434EA9120E3BC10A7D2ECD6723C140A21A032C8') { powershell -ExecutionPolicy Bypass -File tutti-bootstrap.ps1 } else { 'tutti: checksum mismatch, not run' } ``` It installs Tutti and what it needs (Python through uv, gh) in your user space, checking every download's SHA-256, then runs `tutti setup`, which asks nothing: it finds your agents and their sign-ins, GPUs and local models, machines, Android devices and git projects, writes the config, opens each tool's own sign-in, starts the dashboard at login and turns on automatic updates; `tutti self-update` keeps it current (on by default). Run `tutti setup` again any time: it only fills what is missing. Details, uv and pipx, and the household's `--join`: [docs/INSTALL.md](docs/INSTALL.md). ## Quick start: use Tutti from your own agent The one line above already ran `tutti setup`, which also connects every agent it found (`tutti connect --all`: Claude Code, Claude Desktop, Codex, Antigravity, Cursor, Copilot, VS Code, Gemini). Then ask your agent to hand work to Tutti. Each agent gets Tutti's MCP server and a short instruction; your other settings are kept and backed up, `tutti connect --undo ` takes it out, and the dashboard's **Connect your agent** card shows each agent's state with a Test button. See [docs/CONNECT.md](docs/CONNECT.md). Then: ```bash tutti config # checks the file and names every problem with its key tutti machines # free slots, load and yield flag of every machine tutti dashboard # already running at login: http://127.0.0.1:4777/ (its Set up card lists what is left) ``` From source instead: `git clone https://github.com/ventura8/Tutti`, then `install/install.sh` (or `uv tool install git+https://github.com/ventura8/Tutti`), then `tutti setup`. Machines you send work to need `rsync` and `ssh` with key-based login, and Docker if you use the container runner. Source package builds use a pinned setuptools backend and check a literal source list; see [docs/INSTALL.md](docs/INSTALL.md#other-ways). Tutti reads one config per user, whatever folder a command starts in: `$TUTTI_CONFIG`, else `~/.config/tutti/config.yaml` (or `~/.config/tutti/tutti.config.yaml`; `$XDG_CONFIG_HOME` is honoured), and only when neither exists the nearest `tutti.config.yaml` from the current folder upwards. The dashboard, the MCP server, the service and every command resolve the same file. A symlinked config stays a symlink: every save writes its real file. `tutti doctor` and Settings warn about another copy it could pick (the XDG files, the nearest from the current folder) that differs, and merge it in with one click (`tutti doctor --merge-configs`). Nothing personal is built in: hosts, paths and accounts live only in that file. It never holds a secret. ## The CLI | Command | What it does | | --- | --- | | `tutti test ''` | Copies the track's worktree to the first fit machine and runs the command there behind the slot queue, in a memory-capped container or plain bash. `--on ` skips routing; `--dir` names the tree; `--input ` (repeatable) copies a file or folder the job needs to that machine's cache first and hands its folder to the command as `$TUTTI_INPUTS` (read-only in a container). Returns the command's exit code. Steps a command needs first (`test.prepare`, e.g. the e2e build before Playwright) are put in front; a hot machine (`heat`) takes one run, a very hot one none. | | `tutti test --device -- ` | Runs a command against an Android device on the machine its adb sees it on: `ANDROID_SERIAL` set (adb, Gradle's `connectedAndroidTest` and Playwright pick the device from it), the device's lock held so one run at a time uses it (a second waits in the same queue as machine slots), its battery, charging and heat checked first (it waits up to `--wait-minutes` for a phone to charge or cool down), the screen woken. Without a track the current folder is the tree. `--fetch ` copies screenshots, videos and reports back. See [docs/MACHINES.md](docs/MACHINES.md#android-devices). | | `tutti devices [add\|pair\|move\|claim\|release\|install]` | Every Android device: connected, authorised, battery, charging, battery temperature, screen, Wi-Fi, whether a run holds it, and why it is not ready; a wireless device whose port changed is reconnected through mDNS. `pair` pairs one over wireless debugging (a QR code to scan; a TV types the code it shows; USB fallback) and adds it to the config. `move --to [devices]` moves devices to another machine with no re-pairing (the adb key is copied at mode 600), a preflight and a rollback. `add` prints the manual setup. `claim`/`release --who `: a session outside Tutti says it uses a device (it is released, its own settings back, only when every user is done); `install `: debuggable APKs only, one install per device at a time. `hours [,HH-HH] [--days mon-fri]\|off`: recurring blocked hours, when the device is not used at all. See [docs/DEVICES.md](docs/DEVICES.md) and [docs/DISPATCH.md](docs/DISPATCH.md#prep-and-restore). | | `tutti pause\|resume [--stop-now] [--from