FIREFIGHTER

Why

Run three or four agents at once and each one decides on its own to train a model, run an eval sweep, build a Docker image or render something. They all grab the same GPU. VRAM runs out, two trainings slow each other to a crawl, your game stutters, audio crackles, and nobody knows who's using what. FIREFIGHTER gives every agent one queue where it sees what the others are doing, keeps a reserve of the machine for you, and moves their work out of the way when you sit down.

Install (one command)

Windows (PowerShell):

irm https://raw.githubusercontent.com/JoshWright22/FIREFIGHTER/main/scripts/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/JoshWright22/FIREFIGHTER/main/scripts/install.sh | sh

Go 1.23+:

go install github.com/JoshWright22/firefighter/cmd/firefighter@latest && firefighter setup

The installer checks the release checksum, puts one ~8 MB binary on your PATH and runs firefighter setup. No admin rights. Check it with firefighter status; remove it with firefighter uninstall. Requirements and every file it touches: docs/reference.md.

How it works

flowchart TD
    A["Agent session<br/>Claude Code, Codex, Gemini CLI, ..."] -->|"firefighter run<br/>or MCP firefighter_submit"| Q["Queue<br/>least-used project first"]
    Q --> F{"Fits beside the<br/>human's reserve?"}
    F -->|"not yet"| Q
    F -->|yes| R["Runs in your environment,<br/>pinned to one GPU and the CPUs<br/>outside your reserve"]
    R --> H{"You sit down<br/>or start a game?"}
    H -->|no| D["Receipt + do: line"]
    H -->|yes| P["Cooperative pause,<br/>then suspend"]
    P -->|"you leave"| R
    P -->|"you need its memory"| C["Checkpoint and exit<br/>(60 s grace)"]
    C -->|"requeued, same id"| Q

1. An agent sends heavy work through firefighter run (or the firefighter_submit MCP tool) with a time estimate. It waits in a queue where the project that has used the least goes first.
2. A job starts only when its CPU, RAM and VRAM need (learned from past runs) fits next to the reserve FIREFIGHTER keeps for you. GPU jobs are pinned to the card they were admitted on.
3. When you start typing, open a fullscreen app or start a game, your reserve grows within half a second. Jobs are paused, then suspended, and if you need their memory they checkpoint and go back in line on their own.
4. Every reply ends with one market line and a do: with the recommended next step.

What an agent sees (firefighter run, your program's output passes through unchanged):

$ firefighter run --gpu --minutes 40 --vram 10 --name "nanoGPT train" -- python train.py
◆ 3f2a91c0 nanoGPT train waiting #2, starts ~2:05 PM (in 22m): GPU turn queue
   gpu 40m: start ~22m, cost ~42 of 212 (urgent ~6m ~84) (spot ~70m ~14) | busy 15/60/120m 92/35/12% | quiet 02:00 (usually 8% busy) | do: queue it at normal (starts ~22m); keep working meanwhile
◆ nanoGPT train: spotlight's yours (lease 40 min, budget left 212.0)
step 1200 | loss 2.913 ...
◆ nanoGPT train: FIREFIGHTER needs it to stop (VRAM below the human's 8.0 GB reserve); it gets time to save and exit, then it's requeued
◆ stopped to give the human the machine back; back in line automatically (attempt 2). Nothing to do: it restarts when there's room
◆ nanoGPT train: spotlight's yours (lease 40 min, budget left 180.6)
◆ nanoGPT train: curtain call, ok (exit 0) in 21.4 min (declared 40), waited 6.1, charged 18.2 machine-min, peak 3.1 GB RAM / 9.4 GB VRAM

What you see (firefighter status, while you play a game):

$ firefighter status
FIREFIGHTER  human: on stage (game/media) eldenring.exe using 64% of the 3D engine
  reserve for the human: 6 CPUs, 35% RAM, 8.0 GB VRAM
  CPU 9.2/16 busy (5.1 human+other)  RAM 18.4/63.9 GB free  GPU 71%  VRAM 14.9/24.0 GB
  policy: preset balanced, order las, pricing priced, budget karma
  gpu 30m: start ~1.5h, cost ~38 of 168 (spot ~2.1h ~13) | busy 15/60/120m 95/70/31% | quiet 02:00 (usually 8% busy) | do: queue it (starts ~1.5h), or spot if it can wait, or plan it for 02:00

on stage
  3f2a91c0 nanoGPT train                      nanoGPT        until ~2:45 PM paused: the human needs the GPU (eldenring.exe using 64% of the 3D engine)

in the wings
  a81c0d42 #1 eval sweep                      evals          on ~3:20 PM the human needs the GPU (eldenring.exe using 64% of the 3D engine)
  77d0e5b1 #2 docs build                      site           on ~2:31 PM needs 6.0 GB RAM, 4.2 GB free after the human's reserve

budgets (machine-minutes left)
  nanoGPT                  180.6
  evals                    168.5
  site                     240.0

The full mechanics (the decision table, the preemption ladder, the market math) are in docs/how-it-works.md.

What you get

• You come first. A reserve of CPUs, RAM and VRAM that follows your keyboard, fullscreen apps, games, Docker and your own programs.
• Turns instead of fights. One queue, fair share by project, a 45-minute cap on any wait, and VRAM admission learned from each command's past runs.
• Posted prices, no bidding war. Spot (1/3 price), normal and urgent (2x) tiers against a daily budget, summed up in one ~60-token line per reply.
• Polite preemption. CPU set, then pause, suspend, checkpoint and requeue. Kill only when RAM is critical.
• Agents that skip the queue are caught. Heavy work started outside FIREFIGHTER is adopted, billed 1.5x and preempted first.
• Network too. Downloads and installs take turns and wait while you're on a call or gaming.
• Any machine. Any number of NVIDIA, AMD or Intel GPUs, any CPU count, Windows, macOS and Linux. Each PC runs on its own; nothing goes over the network.
• Set and forget. Starts at logon and teaches every agent it finds the protocol.

This is the beginning of the README. Read the rest at the original. Read the full README ↗