Sesiones en segundo plano con agentes de Claude: ejecuta tareas largas sin bloquear tu terminal

Arrancas una tarea grande, una migración, un refactor de tests, una pasada de documentación sobre veinte ficheros, y ahí te quedas mirando cómo trabaja tu terminal. Durante una hora. En ese rato la sesión está ocupada, no puedes hacer otra cosa, y si cierras la ventana el trabajo se pierde. Justo para eso está el comando claude agents. Despacha una sesión al segundo plano, te devuelve el terminal de inmediato y deja a Claude trabajando mientras tú estás en otra cosa. Después recuperas la sesión con --resume, miras, das feedback y sigues. Vamos a montarlo ahora y te enseño las trampas que a mí me costaron tiempo al principio.

Paso 1, pilla la diferencia entre interactiva y despachada

Una sesión normal de Claude Code es interactiva. Tú escribes, Claude responde, esperas, vuelves a escribir. Eso está bien para trabajo en el que quieres estar encima. Una sesión en segundo plano es distinta. Le das un encargo, se pone en marcha, y tú estás fuera del bucle hasta que la vuelvas a abrir. El comando es claude agents. Despacha una o varias sesiones que corren en segundo plano, con sus propios valores por defecto de modelo, effort y permisos.

Importante para gestionar expectativas: segundo plano no significa autónomo y a olvidarse. Tú le pasas las reglas de permisos, y todo lo que no hayas permitido sigue esperándote. Una sesión en segundo plano que se queda parada en cada git push porque no pusiste permiso no te ha servido de nada. Por eso la mitad del trabajo de este playbook consiste en poner los valores por defecto de forma que la sesión de verdad llegue hasta el final.

Paso 2, despacha tu primera sesión en segundo plano

La entrada es un solo comando. Le das a claude agents el modelo y el effort que quieres, y un encargo claro.

claude agents --model sonnet --effort medium

Los flags documentados oficialmente para claude agents son --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort y --dangerously-skip-permissions. Fijan los valores por defecto de la sesión despachada. Regla práctica para empezar: coge --model sonnet para trabajo normal, --effort medium, y no toques --dangerously-skip-permissions hasta que entiendas qué toca la sesión. El motivo está en el paso 7.

Paso 3, dale a la sesión un nombre en vez de un ID críptico

Las sesiones en segundo plano reciben un ID de sesión. Es único, pero nadie se acuerda de a3f9c1e2-.... Dentro de una sesión puedes renombrarla con /rename, y después la recuperas por el nombre en vez de por el ID.

/rename refactor-tests-junio

Hazlo justo al principio de cada sesión en segundo plano que dure más de unos minutos. Cuando tienes tres en paralelo, la diferencia entre "¿cuál era la de los tests?" y un nombre claro es exactamente la diferencia entre estar tranquilo y estar de los nervios.

Paso 4, recupera la sesión con resume

Este es el núcleo. Una sesión en segundo plano sigue trabajando mientras no estás, y cuando quieres mirar, la recuperas. Tres comandos que conviene recordar:

# Una sesion concreta por su ID
claude --resume <session-id>

# Una sesion con nombre en modo print
claude -p --resume refactor-tests-junio

# Simplemente continuar la ultima sesion
claude --continue

--resume con ID o nombre abre exactamente la sesión que quieres. --continue coge la última. El modo print -p te da la respuesta directamente por stdout en vez de en la interfaz interactiva, lo cual va bien cuando solo quieres ver rápido el estado sin meterte en la sesión.

Paso 5, deja que las sesiones en segundo plano trabajen en el directorio correcto

Por defecto Claude Code aísla las sesiones en segundo plano en un worktree de git, para que no te muevan la copia de trabajo bajo los pies mientras tú tecleas en el repo. Eso suele estar bien. A veces estorba, por ejemplo en repos donde los worktrees son incómodos o donde la pipeline de build tiene problemas con dos copias de trabajo.

Para eso está el ajuste worktree.bgIsolation en tu settings.json. Si lo pones a "none", la sesión en segundo plano puede editar directamente en la copia de trabajo en lugar de en un worktree aislado.

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Mi consejo: deja el aislamiento activado mientras tú mismo trabajes en paralelo en el repo. Quítalo solo cuando tengas exactamente un motivo y sepas que no hay una segunda sesión tocando los mismos ficheros a la vez. Dos procesos escribiendo sin coordinación en la misma copia de trabajo es el camino más rápido a un lío de merge que luego limpias a mano.

Paso 6, dale su contexto a la sesión con un hook SessionStart

Una sesión en segundo plano arranca en frío. No sabe lo que sabes tú, más allá de lo que ponga en CLAUDE.md. Si quieres que salga con el contexto correcto, sin escribirlo en el prompt cada vez, usa el hook SessionStart. Se dispara cuando empieza una sesión y puede cargar contexto, fijar un entorno o sacar una nota de tu memoria.

Un hook SessionStart mínimo en settings.json se ve así:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "cat .claude/context-brief.md" }
        ]
      }
    ]
  }
}

La salida acaba en el contexto de la sesión que arranca. En nuestro caso el hook carga un briefing corto con el estado actual, de modo que cada sesión en segundo plano sabe de entrada en qué proyecto está y qué reglas rigen. Si eso todavía no lo has montado en la Academy, lee antes la lección de hooks y skills, van juntos.

Paso 7, cuidado con dangerously-skip-permissions en segundo plano

--dangerously-skip-permissions deja pasar a ciegas todas las llamadas a herramientas. En una sesión interactiva ya es arriesgado, porque un paquete envenenado o una inyección de prompt entra justo por esa puerta. En una sesión en segundo plano es peor, porque no estás al lado. La sesión dispara rm, npm install y git push sin que te enteres en ese momento.

El camino mejor es --permission-mode con una lista de permisos pensada en tus settings. Permite en concreto los comandos que la tarea necesita y deja bloqueado el resto. Si luego la sesión se queda parada en una acción no permitida, la recuperas con --resume, miras qué quería y decides. Es un minuto más de trabajo y te ahorra el día en que una sesión en segundo plano rompe algo que solo ves dos horas después. Si quieres asegurar los comandos de bash en general, mira el playbook de la sandbox de bash, se complementan bien.

Paso 8, despacha varias sesiones para trabajo en paralelo

La palanca de verdad llega cuando dejas correr varias sesiones en segundo plano a la vez. Una escribe tests, otra hace la actualización de documentación, otra limpia un módulo. Cada una recibe su nombre con /rename, sus valores por defecto al despacharla, y tú recoges los resultados cuando terminan.

Lo importante: dale a cada sesión un encargo bien delimitado. Tres sesiones que trastean todas en el mismo módulo se pisan entre ellas, sobre todo si has desactivado el aislamiento por worktree del paso 5. Tres sesiones trabajando en tres esquinas distintas sí que son paralelismo real. El patrón es el mismo que con sesiones interactivas en paralelo con worktrees de git, solo que tú no estás sentado en cada una.

Paso 9, constrúyete una rutina para recoger

Las sesiones en segundo plano tienen un punto ciego. Si no miras, no sabes si están terminadas, bloqueadas o si se han ido por el camino equivocado. Mi montaje contra eso es simple: una vez por la mañana y otra a última hora de la tarde repaso las sesiones abiertas. --resume, leer el estado, dar feedback o dar el visto bueno, salir.

Si quieres automatizarlo, combínalo con las rutinas programadas del playbook correspondiente. Una rutina que te mande dos veces al día un resumen corto de las sesiones en marcha al chat o como notificación te quita el ir detrás. El asunto no es la tecnología, es la costumbre. Una sesión en segundo plano que nadie recoge es una sesión que igual te podías haber ahorrado.

Paso 10, ordena y nombra con criterio

Después de unos días con sesiones en segundo plano tienes una lista de sesiones viejas que ya no hacen nada. Repásalas, abre una vez las terminadas con --resume para asegurarte de que no queda nada pendiente, y déjalas estar. Lo que queda es la disciplina al nombrar. Una convención de nombres consistente, por ejemplo tarea-modulo-fecha, marca la diferencia entre una lista de sesiones útil y un montón de IDs crípticos.

Mi error al principio fue tirar de --continue para todo porque es lo más cómodo. Entonces tenía tres sesiones en segundo plano y --continue cogía siempre la última tocada, no la que yo quería. Desde entonces renombro con /rename cada sesión que vive más de diez minutos y la recupero por el nombre. Suena a menudencia, pero es la diferencia entre "sé qué está corriendo" y "¿por qué me ha cambiado esto ahora?".

Qué sigue

Cuando las sesiones en segundo plano estén asentadas, el siguiente paso lógico es el montaje headless para CI/CD, o sea Claude Code sin terminal dentro de una pipeline. Para eso hay un playbook propio. Y si empiezas a llevar varias sesiones en paralelo, lee el playbook de sesiones paralelas con worktrees de git, explica con más detalle el aislamiento del paso 5. En el nivel 5 de la Academy se trata el patrón CEO-worker, que es el escalón siguiente cuando no solo quieres correr sesiones en paralelo, sino además coordinarlas.

Source

Specs verificadas contra el CHANGELOG oficial de Claude Code y la referencia de la CLI:

• CHANGELOG de Claude Code (flags de claude agents, worktree.bgIsolation, resume por ID y por nombre): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Referencia de la CLI de Claude Code: https://code.claude.com/docs/en/cli-reference
• Hook SessionStart: https://code.claude.com/docs/en/hooks