Documentación

Instalar y correrlo

Necesita Node ≥ 22.6. No hay paso de build: el CLI se ejecuta desde TypeScript directamente.

Linux — apt

# una vez: la clave y el repo
$ sudo install -d -m 0755 /etc/apt/keyrings
$ curl -fsSL https://quartermaster.legios.com.ar/apt/legios.gpg \
    | sudo tee /etc/apt/keyrings/legios.asc >/dev/null
$ echo "deb [signed-by=/etc/apt/keyrings/legios.asc] \
    https://quartermaster.legios.com.ar/apt stable main" \
    | sudo tee /etc/apt/sources.list.d/legios.list >/dev/null
$ sudo apt update && sudo apt install quartermaster

macOS — Homebrew

$ brew install legiosai/tap/quartermaster

Cualquier sistema — npm

$ npm install -g @legios/quartermaster

Desde el código

$ git clone https://github.com/legiosai/quartermaster
$ cd quartermaster && make instalar

Todas las banderas

Sin argumentos lee del disco y no toca la red. Todo lo que sale por red está detrás de una bandera explícita.

Cómo leer lo que muestra

Cada cuenta trae dos números a propósito. El primero es la sesión y el segundo la barra que te frena antes. Contestan preguntas distintas —«¿puedo seguir ahora?» y «¿llego al final de la semana?»— y una sola de las dos deja media respuesta. Cuando la que frena es la sesión, se muestra un número solo.

$ qm --breve
personal 23/75%! · teams 9/42% · codex 49/59%

¿Te vas a chocar antes de que se reinicie?

Es la pregunta que ni el porcentaje ni el consumo contestan solos: «vas 75 %» no dice nada sin saber a qué velocidad subís. qm guarda una serie de lecturas por barra y le ajusta una recta.

ritmo: 12.4 pts/h · 100 % en 1h58m — antes del reinicio

Lo importante no es la recta: es cuándo no se dibuja. Con dos lecturas, o con una ventana que recién arranca, cualquier extrapolación es un número inventado con cara de dato. Entonces dice esto, que es otra cosa:

ritmo: todavía no sé el ritmo: hacen falta 3 lecturas y hay 1

• Se descartan las lecturas de más de 2 horas: el ritmo de hace cuatro no predice el de ahora.
• No se proyecta sobre un movimiento menor a 2 puntos, porque el servidor manda enteros y subir uno no se distingue de un redondeo.
• La serie vive en ~/.cache/quartermaster/historial.jsonl y se indexa por el medidoEn de la cuota, no por cuándo miró qm: leer diez veces el mismo cache deja una muestra.

--json emite la respuesta, no los datos crudos

Las cuatro superficies —GNOME, la barra de macOS, la bandeja de Windows y el navegador— dibujan lo mismo porque ninguna decide nada. La regla que elige qué barra mostrar vivía copiada en Python, JavaScript y Swift, y una regla en tres lenguajes es una respuesta distinta por pantalla el día que alguien edita una. Ahora el CLI emite la respuesta ya resuelta y los dibujantes leen campos.

$ qm --json --redactado
{
  "generado": "2026-09-10T23:04:07.315Z",
  "plataforma": "linux",
  "ventanaDias": 7,
  "perfiles": [
    {
      "producto": "claude",
      "perfil": ".claude",
      "directorio": "~/.claude",
      "cuenta": "***@ejemplo.com",
      "plan": "claude_max",
      "credencial": "vigente (4h29m)",
      "cuota": {
        "estado": "ok",
        "origen": "endpoint",
        "medidoEn": "2026-09-10T22:56:23.201Z",
        "edadSegundos": 464,
        "ventanas": [ … ],
        "mostrar": [ … ],
        "frena":   { "clave": "weekly_scoped", "porcentaje": 89, … },
        "sesion":  { "clave": "session",       "porcentaje": 36, … },
        "semanal": { "clave": "weekly_scoped", "porcentaje": 89, … },
        "historia": [ … ]
      },
      "proyeccion": { … },
      "local": { … }
    }
  ]
}

La raíz

Cada perfil

Las cinco pantallas

Todas salen de qm --json. Ninguna sabe qué es una credencial.

La statusline, en el settings.json del perfil

{
  "statusLine": { "type": "command", "command": "qm --breve" }
}

Ojo con lo que no hace: el cache se refresca cuando ese perfil corre Claude Code, así que la statusline de un perfil se actualiza usándolo. Alcanza para enterarte de que vas al 75 % mientras trabajás, y no para vigilar un perfil que no estás usando.

De dónde sale cada número

• La cuota sale de cachedUsageUtilization, dentro del .claude.json de cada perfil. Ya está en el disco: no hace falta ni red ni credencial, y por eso se lee aunque el token esté vencido.
• Los perfiles se descubren mirando todos los CLAUDE_CONFIG_DIR de la máquina, no sólo el directorio por defecto. Un asiento de trabajo y una suscripción personal son dos perfiles, y las demás herramientas ven uno.
• El consumo sale de las transcripciones locales, en la ventana de --dias. Es el piso: siempre hay un número, aun con todos los tokens vencidos.
• Codex no deja la cuota en el disco, así que ese cache es nuestro: se refresca solo si está viejo, salvo en --breve, que tiene que seguir tardando milisegundos.
• opencode aporta los proveedores que tenga configurados, con el mismo tratamiento.

Lo que no hace, a propósito

• Nunca refresca un token. Lee credenciales, no las escribe. Refrescar sería correr una carrera contra la escritura del propio Claude Code y arriesgar el refresh token del usuario: cambiar una comodidad de monitoreo por un login roto. Cuando una credencial vence, lo dice y sigue con el resto.
• Sin cuenta, sin nube, sin telemetría. Todo se lee del disco y de la credencial del usuario. Lo único que sale de la máquina es el sondeo de cuota, al mismo host con el que Claude Code ya habla.
• Ese sondeo tiene piso: 60 segundos. Una cadencia adaptativa llegó a bajar a 20 s por cuenta —unas 360 consultas por hora, sostenidas, contra un endpoint no documentado—. Que te limiten por leer tu propia cuota sería una versión autoinfligida del silencio que la herramienta existe para arreglar.
• El adaptador de transcripciones no es opcional. El endpoint no está documentado y puede desaparecer sin aviso; el piso local es lo que garantiza que siempre haya un número.

Códigos de salida

# no arrancar un trabajo largo si ya vamos al 80
$ qm --umbral=80 >/dev/null || exit 0

# o directamente esperar a que baje
$ qm --esperar --cuenta=codex && codex exec "…"

Si algo no anda

Dice que la credencial está vencida

Es correcto y no rompe nada: la cuota igual se lee, porque sale del disco. El mensaje dice qué comando la arregla. qm no lo corre por vos a propósito.

El número tiene un ~ al lado

El cache tiene más de 6 horas. Corré qm --refrescar, o simplemente usá ese perfil: Claude Code reescribe el cache cuando corre.

Falta una cuenta

Fijate con qm --json si aparece en perfiles. Si no está, su CLAUDE_CONFIG_DIR no está en el ambiente desde el que corrés qm.

En GNOME no aparece la barra de arriba

Hace falta la extensión y una sesión nueva: GNOME carga extensiones al iniciar sesión, así que después de instalarla hay que salir y volver a entrar.

Otra cosa

Abrí un issue. Si podés, pegá la salida de qm --json --redactado: está pensada exactamente para eso — saca mails y rutas de casa para que se pueda comitear.