Receta · Intermedio · 10 min

Límite de uso de Claude Code: haz que tus 5 h y la semana duren

Lee /usage y /context para ver qué se come tu límite de Claude Code y corrige cada causa: contexto, caché, subagentes, modelo y esfuerzo.

Probado con Claude Code 2.1.316 · revisado 2026-11-01

Ver los archivos en GitHub Gratis · licencia MIT

El problema

Tu sesión de 5 horas o tu límite semanal se acaban antes de tiempo y no sabes por qué. Lo habitual es instalar una skill «para ahorrar tokens» sin mirar qué está gastando de verdad. Casi siempre son unas pocas causas: un contexto que arrastras todo el día, fallos de la caché, subagentes y flujos que corren en paralelo y sesiones que siguen vivas.

La solución

Claude Code 2.1.316 ya trae lo necesario para verlo: /usage (alias /cost y /stats) muestra cuánto llevas, qué lo consume y qué cambiar, y la tecla f aplica parte de los arreglos. Primero se mide y después se corrige cada causa con un comando concreto, sin herramientas externas.

Diagnóstico en 1 minuto, dentro de Claude Code:

/usage            # barras de 5 h y semana + qué lo consume (d = 24 h, w = 7 días, f = aplicar arreglos)
/context          # qué ocupa tu ventana de contexto ahora mismo
/effort status    # esfuerzo actual
/tasks            # trabajo en segundo plano de esta sesión
/clear            # empezar limpio al cambiar de tarea (gratis)

Lo mismo sin abrir la interfaz (no consume la conversación):

claude -p "/usage"
claude -p "/context"
claude agents          # sesiones en segundo plano
claude stop <id>       # parar una que ya no necesitas

1. Mira primero cuánto llevas y qué lo consume: /usage

Escribe /usage en la sesión (también funcionan /cost y /stats, que son alias). En un plan Pro, Max, Ultra, Team o Enterprise verás tres bloques:

las barras del plan (sesión actual de 5 h, semana con todos los modelos y, si aplica, semana de un modelo concreto), cada una con su hora de reinicio;
un bloque «What's contributing to your usage?» con recomendaciones;
la atribución por skills, subagentes, plugins y servidores MCP.

Pulsa d o w para alternar entre las últimas 24 horas y los últimos 7 días. Cada recomendación empieza con un porcentaje: no es lo que ahorras, sino la parte de tu uso a la que se aplica, y varias filas pueden sumar más del 100 %. Las cifras son aproximadas y salen del historial de este equipo: no incluyen lo que uses desde otro PC o en claude.ai.

Ejemplo real de un PC con Max (1-nov-2026):

96 % Give general-purpose subagents a cheaper model
36 % Start fresh when you switch tasks · run /clear
35 % Save workflows for big tasks · 315 agents ran

Con eso ya sabes por dónde empezar. El bloque Session (coste en dólares) es una estimación a precio de lista pensada para quien paga por API: con suscripción no es tu factura.

2. Aplica los arreglos automáticos con la tecla f

Desde la 2.1.305, si el pie de /usage dice algo como «f to fix 2 of 3», pulsa f. Claude Code hace dos cosas:

ejecuta directamente las filas que terminan en un comando /effort (por ejemplo «Switch from max to high effort · /effort high»);
para el resto de filas que puede tratar, envía a Claude un único mensaje con un paso por fila y le pide que te enseñe cada cambio antes de hacerlo.

Las filas que terminan en «run /compact» o «run /clear» no se aplican solas: ese comando lo escribes tú. Las que proponen recortar un archivo (por ejemplo «Trim ~/code/api/CLAUDE.md · 49k tokens per request») pueden entrar en el mensaje o quedarse para ti. En «f to fix 2 of 3», el primer número es lo que se aplicará y el segundo lo que se muestra. Si tienes Remote Control conectado no aparece la pista f: desconéctalo y vuelve a abrir /usage. Revisa siempre lo que Claude propone tocar antes de aceptarlo: es tu configuración.

3. Contexto largo: /clear entre tareas y /context para ver el peso

Claude Code envía toda la conversación en cada petición, y cada uso de herramientas manda otra petición con esos resultados. Aunque la caché abarata la relectura, una pregunta de una línea en una sesión abierta todo el día sigue gastando por toda la conversación. Tres hábitos:

/clear al cambiar a una tarea sin relación (antes, /rename para encontrarla luego con /resume). /clear no cuesta nada; /compact sí, porque lee toda la conversación para resumirla. Más detalle en /clear vs /compact.
/context muestra la cuadrícula de lo que ocupa tu contexto: prompt del sistema, herramientas, MCP, archivos de memoria (CLAUDE.md), skills y mensajes, con sugerencias.
Mantén CLAUDE.md por debajo de unas 200 líneas y pasa a skills las instrucciones que solo usas a veces: las skills se cargan solo cuando se invocan (ver un CLAUDE.md que funciona).

Si /context muestra un servidor MCP que no usas, desactívalo en /mcp; y si existe un CLI equivalente (gh, aws, gcloud), la documentación lo considera más barato en contexto (ver MCP para programadores).

Si compactas, dile qué conservar con una sección en CLAUDE.md:

# Compact instructions
Al compactar, conserva los mensajes de error exactos, las rutas de archivos tocados y el porqué de cada decisión.

4. La caché: qué la rompe y cómo verlo en /cost

Con suscripción y dentro del uso del plan, la conversación principal usa una caché de una hora; con créditos de uso, clave de API o un proveedor en la nube baja a cinco minutos. El primer mensaje tras una pausa más larga que esa vida útil reprocesa todo el contexto.

Desde la 2.1.251, /cost (alias de /usage) añade una línea «Prompt cache (main)» con el porcentaje servido desde caché, los fallos, los tokens recacheados y si la caché está caliente o fría; desde la 2.1.260 nombra la causa probable del último fallo.

Lo que invalida la caché según la documentación:

cambiar de modelo con /model;
cambiar el esfuerzo en la mayoría de modelos (en Opus 5.5, Sonnet 5.5, Haiku 5.5 y Fable 5.1 con clave o suscripción se conserva);
activar o desactivar el modo rápido;
conectar o quitar un servidor MCP, o activar o desactivar un plugin;
denegar una herramienta entera;
compactar, acumular muchas imágenes y actualizar Claude Code.

Regla práctica: elige modelo, esfuerzo y modo rápido al empezar, no a mitad de sesión; y no retomes con /resume una sesión enorme y fría solo para una pregunta.

5. Subagentes, flujos y agentes en segundo plano que gastan sin que mires

Cada subagente y cada agente de un flujo dinámico hace sus propias peticiones, además de las de la conversación principal; el bloque de atribución de /usage muestra su parte. Medidas concretas:

Dale un modelo más barato a los subagentes sencillos: model: haiku en el frontmatter del subagente, o la variable CLAUDE_CODE_SUBAGENT_MODEL como valor por defecto (la definición del agente y el modelo de cada llamada mandan sobre ella desde la 2.1.251).
Desde la 2.1.316, CLAUDE_CODE_SUBAGENT_EFFORT fija el esfuerzo de los subagentes que no tengan otro, en vez de heredar el de la sesión.
Revisa /tasks: lista el trabajo en segundo plano de la sesión, incluidos subagentes terminados; para lo que siga vivo y no necesites, páralo.
Fuera de la sesión, claude agents lista las sesiones en segundo plano y claude stop <id> las detiene.
Ojo con /loop y las tareas programadas: se ejecutan aunque estés inactivo y envían todo el contexto; /usage tiene una fila Loops desde la 2.1.243.

Los equipos de agentes gastan unas 7 veces más tokens cuando los compañeros trabajan en modo plan, según la documentación.

Las dos variables, en ~/.claude/settings.json (junto con la barra de estado del paso 7):

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_EFFORT": "low"
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  }
}

6. Modelo y esfuerzo: no uses el más caro para todo

La documentación oficial lo resume así: Sonnet resuelve bien la mayoría de tareas de programación y cuesta menos que Opus; reserva Opus para decisiones de arquitectura o razonamiento de varios pasos. Cambia con /model (con s en el selector lo aplicas solo a esta sesión) o lanza cada terminal con --model. Recuerda el paso 4: cambiar de modelo a mitad de conversación pierde la caché, así que mejor al empezar.

El esfuerzo también cuenta: en Opus 5.5, Sonnet 5.5 y Haiku 5.5 el valor por defecto es medium; /effort status te dice cuál tienes (en nuestro PC: «auto (currently medium)») y /usage avisa si estás en max. max solo dura la sesión.

Si un mensaje dice «You've hit your session limit» o «weekly limit», cambiar de modelo no te devuelve el acceso porque ese límite es común a todos los modelos; con «You've hit your Opus limit» sí puedes seguir con otro modelo. Mientras esperas: /rate-limit-options ofrece esperar y continuar solo tras el reinicio (2.1.234 o posterior) y /usage-credits, si tienes créditos de uso activados.

7. Vigílalo sin abrir /usage: barra de estado con 5 h y semana

La barra de estado recibe por la entrada estándar un JSON con rate_limits.five_hour.used_percentage y rate_limits.seven_day.used_percentage (solo en Pro, Max y Ultra, y después de la primera respuesta de la sesión), además de context_window.used_percentage. Con un script de pocas líneas ves en todo momento el modelo, el contexto y los dos límites. Usa python3 para no depender de jq.

Guárdalo como ~/.claude/statusline.sh:

#!/bin/bash
# Barra de estado de Claude Code: modelo, contexto y límites de 5 h y semanal (sin jq)
python3 -c '
import json, sys
d = json.load(sys.stdin)
ctx = (d.get("context_window") or {}).get("used_percentage") or 0
partes = ["[%s] contexto %d%%" % (d.get("model", {}).get("display_name", "?"), ctx)]
rl = d.get("rate_limits") or {}
for clave, nombre in (("five_hour", "5 h"), ("seven_day", "semana")):
    v = (rl.get(clave) or {}).get("used_percentage")
    if v is not None:
        partes.append("%s %d%%" % (nombre, v))
print(" · ".join(partes))
'

Dale permisos con chmod +x y añade a ~/.claude/settings.json la clave statusLine del paso 5. Con la barra a la vista, la regla es simple: si el contexto pasa del 60-70 % y vas a cambiar de tarea, /clear; si la ventana de 5 h va alta, deja para después lo que pueda lanzar muchos agentes.

Compruébalo

Prueba la barra sin abrir Claude, pasándole un JSON de ejemplo:

chmod +x ~/.claude/statusline.sh
echo '{"model":{"display_name":"Opus 5.5"},"context_window":{"used_percentage":42.3},"rate_limits":{"five_hour":{"used_percentage":23.5},"seven_day":{"used_percentage":41.2}}}' | ~/.claude/statusline.sh

Salida esperada:

[Opus 5.5] contexto 42% · 5 h 23% · semana 41%

Lo que probamos en un PC con Linux, Claude Code 2.1.316 y cuenta Max (1-nov-2026): claude -p "/usage" devolvió las barras de sesión y semana, las recomendaciones y la atribución por subagentes y MCP; claude -p "/context" devolvió la tabla por categorías; /effort status con Opus 5.5 respondió «auto (currently medium)»; y el script de la barra funcionó con el JSON de ejemplo. Lo que no hemos medido todavía: el ahorro real a lo largo de varios días tras aplicar f, /clear y subagentes con haiku (compáralo tú con d y w en /usage), ni la línea «Prompt cache (main)» en la interfaz, que no sale con -p.

Por qué funciona

Cada petición envía la conversación entera, así que el tamaño del contexto, los fallos de caché y el número de agentes que hacen peticiones a la vez son lo que mueve tu consumo. /usage reparte ese consumo por origen y propone el cambio que más pesa, en vez de que adivines. Las fuentes: costes, caché de prompts, barra de estado, comandos, configuración de modelos y el CHANGELOG.

Errores típicos

Cambias a Sonnet y sigues bloqueado → el aviso era «session limit» o «weekly limit», comunes a todos los modelos → espera al reinicio (/rate-limit-options) o usa /usage-credits.
No aparece la pista f en /usage → tienes Remote Control conectado → desconéctalo y vuelve a abrir /usage.
Sumas los porcentajes de las recomendaciones y pasan del 100 % → no son ahorros, sino la parte del uso a la que se aplica cada una → empieza por la fila más alta.
La caché se enfría a mitad de sesión → cambiaste de modelo, esfuerzo o modo rápido, o tocaste MCP o plugins → elige todo eso al empezar.
La barra de estado no aparece → un statusLine personalizado necesita que hayas aceptado la confianza en la carpeta → acéptala; claude --debug registra el motivo.
La barra no muestra 5 h ni semana → rate_limits solo llega en Pro, Max y Ultra, y después de la primera respuesta de la sesión → envía un mensaje y vuelve a mirar.

Preguntas frecuentes

¿Cuántos mensajes o tokens da cada plan en 5 horas?

No hay una cifra fija publicada en la documentación de Claude Code: depende del plan, del modelo y del tamaño del contexto. Consulta claude.com/pricing para tu plan y /usage para ver tu porcentaje real y la hora de reinicio.

¿Por qué /usage me muestra un coste en dólares si pago suscripción?

El bloque Session es una estimación a precio de lista pensada para API. Con Pro, Max o Ultra lo relevante son las barras del plan y el desglose.

¿Cambiar a Sonnet me devuelve el acceso si me quedé sin límite?

Si el aviso es de sesión o semanal («session limit», «weekly limit»), no: es común a todos los modelos. Si es «Opus limit», sí puedes seguir con un modelo de otra familia.

¿Los agentes en segundo plano gastan aunque no los mire?

Sí: cada subagente, flujo, tarea programada o compañero de equipo hace sus propias peticiones. /usage muestra su parte y /tasks o claude agents te dejan ver y parar lo que siga vivo.

¿/usage incluye lo que uso en otro PC o en claude.ai?

No. El desglose es aproximado y se calcula con el historial de este equipo; las barras del plan sí reflejan tu cuenta.

¿/compact ahorra límite?

A la larga reduce lo que envías en cada mensaje, pero compactar es en sí una petición grande. Si no necesitas continuidad, /clear no cuesta nada.

Toda la biblioteca