Configuración

OpenLimiter guarda todo en un solo directorio de estado bajo tu propia cuenta de usuario: un archivo de configuración, una caché, un bloqueo y el documento manual opcional. Esta página dice dónde está eso y qué hace cada archivo.

El directorio de estado

Dónde vive el directorio de estado en cada plataforma
plataforma	ruta
Windows	`%LOCALAPPDATA%\openlimiter`
macOS	`~/Library/Application Support/openlimiter`
Linux	`${XDG_STATE_HOME:-~/.local/state}/openlimiter`

El directorio se crea con permisos restrictivos donde la plataforma los admite. Una ruta que resulta ser un enlace simbólico se rechaza en vez de seguirse.

Qué vive ahí

Archivos dentro del directorio de estado
archivo	rol
`openlimiter-config.json`	Escrito por `openlimiter init`. Registra la lista de connectors, si cada uno fue detectado, y el layout del statusline.
`openlimiter-cache.json`	La única caché que toda orden lee y en la que se combina todo escritor.
`openlimiter.lock`	Solo lo mantienen los escritores. Los lectores nunca lo toman.
`manual.json`	Opcional. Quota que mantienes a mano. Consulta ingesta para ver la forma.

Cómo se comporta la caché

Un esquema, un archivo, un bloqueo. No hay archivos de estado en competencia que reconciliar.
Los lectores nunca toman el bloqueo. Un lector abre el archivo, valida ese descriptor abierto y lee a través de él, así que una ruta cambiada después de la verificación no puede redirigir los bytes.
Los escritores toman el bloqueo, y la lectura, la combinación y la escritura ocurren todas dentro de él. Un bloqueo con más de cinco segundos se trata como abandonado y se recupera.
Cada reemplazo se guarda en almacenamiento estable antes del renombrado, así que un lector observa el contenido anterior o el nuevo, y nunca un archivo parcial.

La salud de la caché es visible en cualquier momento a través de openlimiter doctor, que imprime el estado de la caché y cuántas filas se descartaron por fallar la validación.

El layout del statusline

El statusline dibuja una celda compacta por proveedor: un nombre, una barra de cinco bloques y el porcentaje, con el código de motivo general y la recomendación de enrutamiento al frente de la fila. Seis claves en el archivo de configuración deciden cómo se construye esa fila, y openlimiter config es cómo se leen y se cambian.

capturado el 10 August 2026, datos sintéticos

NO_COLOR=1 node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP PREFER ANTIGRAVITY  CLAUDE ###.. 64.0%  CODEX ####. 84.0%  ANTIGRAVITY #.... 28.0%  OPENCODE ####. 92.0%
MANUAL #.... 35.0%  OPENROUTER ###.. 62.3%

Cada clave

Las claves del statusline y qué acepta cada una
clave	acepta	significado
`order`	ids de proveedor, separados por comas, o `NONE`	El orden en que aparecen las celdas. Lo que listes va primero; cada proveedor que dejes fuera sigue el orden incorporado detrás de eso, que son los planes de suscripción y luego los meters de crédito y API. `NONE` es la forma de volver a ese orden incorporado. Por defecto `NONE`.
`meters`	`worst` o `all`	Un proveedor con varios meters muestra el más cercano a su límite, o todos como celdas separadas nombradas `PROVIDER:METER`. Los meters se ordenan sesión, diario, semanal, mensual, créditos. Por defecto `worst`.
`width`	un número entero de 40 a 400	Las columnas que una fila puede gastar antes de que la línea se apile. Nada mide tu terminal: un host de statusline corre la orden sin ninguna terminal conectada, así que el número aquí es el número que se respeta. Por defecto `140`.
`rows`	`1` o `2`	Cuántas filas puede usar el layout. Por defecto `2`.
`bars`	`true` o `false`	False restaura la única línea plana de 0.1.0, byte por byte. Por defecto `true`.
`color`	`auto`, `always`, o `never`	`auto` sigue a la terminal, que para un host de statusline normalmente significa sin color, porque el host captura la salida en vez de entregarle una terminal a la orden. `always` es la forma de decir que el host entiende los códigos de escape. Por defecto `auto`.

Leerlas y escribirlas

capturado el 10 August 2026

openlimiter config get statusline
statusline.order=NONE
statusline.meters=worst
statusline.width=140
statusline.rows=2
statusline.bars=true
statusline.color=auto

Una clave a la vez, validada antes de escribirse. Un valor que la clave no puede usar sale con 2 y nombra lo que esperaba, y no se escribe nada parcial, porque todo el documento se reemplaza de forma atómica. Las claves del statusline son lo único que esta orden modifica: la lista de connectors le pertenece a openlimiter init, y cualquier otra clave sale con 2.

openlimiter config set statusline.order codex,claude
statusline.order=codex,claude

openlimiter config set statusline.meters all
statusline.meters=all

openlimiter config set statusline.width 12
openlimiter config: statusline.width must be a whole number from 40 to 400.

openlimiter config set statusline.theme dark
openlimiter config: unknown statusline key. Known keys: order, meters, width, rows, bars, color.

Volver a correr openlimiter init conserva lo que ya está configurado aquí y solo vuelve a detectar los connectors. Una clave del statusline que esta versión no puede leer recurre a su valor por defecto en vez de detener el dibujo, así que un error de tipeo hecho a mano en un campo nunca te cuesta los otros cinco.

Cuando la fila se queda sin espacio

La línea se apila en vez de truncarse. Un salto cae entre dos celdas y nunca dentro de una, y dos filas es el límite. Pasado eso, se conservan los proveedores más cercanos a su límite, y la última fila termina diciendo cuántos no pudo mostrar.

capturado el 10 August 2026, datos sintéticos

openlimiter config set statusline.rows 1 && NO_COLOR=1 node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP PREFER ANTIGRAVITY  CODEX ####. 84.0%  OPENCODE ####. 92.0%  +4 more

La línea de 0.1.0, si la pides

El formato antes de este layout era una sola línea plana sin barras. Si escribiste un script contra eso, bars false la devuelve exactamente, y una prueba fija esa cadena exacta para que no pueda desviarse.

capturado el 10 August 2026, datos sintéticos

openlimiter config set statusline.bars false && node packages/cli/dist/bin.js statusline
OpenLimiter NEAR_CAP CLAUDE 64.0% OPENROUTER 62.3% CODEX 84.0% ANTIGRAVITY 28.0% OPENCODE 92.0% MANUAL 35.0% PREFER ANTIGRAVITY

Ajustes de Claude Code

Usa la ruta absoluta de tu clon. Las barras diagonales funcionan en cualquier plataforma, incluyendo Windows.

settings.json

{
  "statusLine": {
    "type": "command",
    "command": "node /absolute/path/to/openlimiter/packages/cli/dist/bin.js statusline"
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node /absolute/path/to/openlimiter/packages/cli/dist/bin.js hook"
          }
        ]
      }
    ]
  }
}

Cuál de los dos escribe

Solo el statusline. Es la ruta que recibe la carga de sesión, así que es la ruta que actualiza la caché. El hook lee y nunca escribe.

Credenciales

La llamada a la librería de credenciales está detrás de una interfaz, y el adaptador está en stub en este release, así que openlimiter init no puede guardar una clave hasta que se suministre un driver. Nada más en tu máquina se toca.

Detección de connectors

La detección es una función pura del entorno que la CLI le entrega a un connector. Los hechos que solo la CLI puede observar, como un documento manual en el directorio de estado, llegan como marcadores explícitos, y por eso openlimiter doctor nunca afirma que un connector está listo cuando no pudo recibir datos.

terminal

openlimiter doctor
CONNECTOR DETECTED FRESHNESS DRIFT
claude no unknown UNVERIFIED
openrouter no unknown UNVERIFIED
codex no unknown UNVERIFIED
antigravity no unknown UNVERIFIED
opencode no unknown UNVERIFIED
manual yes fresh UNVERIFIED
CACHE ok DROPPED 0

Una caché que no se pudo analizar, o una que se analizó con filas descartadas, agrega una línea más en rojo diciéndolo. Lo reporta contra la caché en vez de contra un proveedor, porque un archivo corrupto no se puede confiar en decir de quién era la lectura que tenía.