Cómo ejecutar agentes de Claude Code en segundo plano

Cinco formas de ejecutar Claude Code en segundo plano

Se diferencian en qué tiene que seguir en marcha y en quién inicia el trabajo.

Tareas en segundo plano dentro de una sesión

Pulsa Ctrl+B mientras Claude ejecuta un comando Bash o un subagente para enviarlo al segundo plano (dos veces en tmux) y sigue hablando con Claude. Claude también puede iniciar por su cuenta un comando en segundo plano. Los subagentes que lanza Claude se ejecutan en segundo plano por defecto.

Escribe /tasks para ver los shells y subagentes en marcha y revisarlos. En una sesión de terminal local, un comando en segundo plano no tiene límite de tiempo, pero se detiene cuando Claude Code se cierra. Para ejecutar varios agentes en paralelo, consulta cómo ejecutar varios agentes de Claude Code.

Agent view: sesiones que sobreviven al terminal

claude --bg "<prompt>" inicia una sesión en segundo plano y vuelve al momento; /bg manda al segundo plano la sesión en la que estás. Un proceso supervisor las ejecuta, así que cerrar el terminal no las detiene, pero apagar o reiniciar el ordenador sí, y una sesión inactiva sin nadie conectado se detiene al cabo de una hora aproximadamente.

claude agents abre la agent view; claude attach <id>, claude logs <id> y claude stop <id> gestionan una sesión concreta. La agent view es una vista previa de investigación (research preview), así que los comandos pueden cambiar.

Ejecuta Claude Code en modo headless con claude -p

1. Ejecuta un prompt y termina

   -p (o --print) ejecuta Claude Code sin la interfaz interactiva y termina cuando acaba, con el código de salida 0 si todo va bien. También puedes pasarle la entrada por una tubería.

   claude -p "List the failing tests and why they fail"
   cat error.log | claude -p "Explain this error"

2. Obtén una salida que un script pueda leer

   --output-format json devuelve el resultado con el ID de sesión y metadatos, incluido total_cost_usd, una estimación calculada en tu máquina. stream-json (con --verbose) emite los eventos a medida que ocurren.

   claude -p "Summarize this repo" --output-format json | jq -r '.result'

3. Permite solo las herramientas que necesita

   En modo headless no hay nadie para aprobar una solicitud. Desde la v2.1.302, una ejecución sin modo definido empieza en Manual y deniega todo lo que necesitaría aprobación. Usa --allowedTools para lo que puede hacer y --permission-mode dontAsk para denegar el resto en lugar de esperar.

   claude -p "Run the test suite and summarize failures" \
     --permission-mode dontAsk --allowedTools "Read,Bash(npm test)"

4. Pon un límite a la ejecución

   --max-turns se detiene tras un número de turnos del agente, y --max-budget-usd al llegar a un coste estimado (puede pasarse un poco). Los dos funcionan solo con -p.

   claude -p "Fix the lint errors" --max-turns 15 --max-budget-usd 3

5. Continúa la misma conversación más tarde

   Guarda el ID de sesión de la salida JSON y pásalo a --resume, o usa --continue para la sesión más reciente del directorio.

   id=$(claude -p "Start a code review of src/" --output-format json | jq -r '.session_id')
   claude -p "Now check the tests too" --resume "$id"

6. Prográmalo con cron

   La documentación de Anthropic no incluye un ejemplo de cron; este usa solo flags documentados. Cron tiene un PATH mínimo, así que usa la ruta completa que da which claude y crea antes la carpeta de logs. No añadas --bare aquí: se salta el inicio de sesión de tu suscripción y necesita una clave de API.

   # crontab -e: los días laborables a las 9:00
   0 9 * * 1-5  cd /path/to/repo && /path/to/claude -p "Summarize yesterday's commits and list new TODO comments. Do not edit files." --permission-mode dontAsk --allowedTools "Read,Bash(git log *),Bash(git diff *)" --max-turns 10 --output-format json >> "$HOME/logs/claude-daily.log" 2>&1

Fuente: documentación del modo headless de Anthropic

Permisos para ejecuciones sin supervisión

• dontAsk más una lista --allowedTools es la opción más cerrada: deniega todo lo que no esté en la lista.
• auto deja que un clasificador revise cada acción en lugar de ti. Anthropic advierte que no garantiza la seguridad.
• acceptEdits aprueba las ediciones de archivos y los comandos de archivo sencillos, pero no otros comandos de shell.
• bypassPermissions se salta las solicitudes y las comprobaciones de seguridad. Anthropic indica que solo se use en contenedores o máquinas virtuales aislados y sin acceso a internet, ya que no ofrece protección frente a la inyección de prompts.
• Para reglas que se apliquen a todas las ejecuciones de un proyecto, pon permissions.allow y permissions.deny en .claude/settings.json. Las reglas de denegación siempre ganan.

Opciones en la nube: cuando tu ordenador está apagado

• Sesiones en la nube: claude --cloud "<task>" se ejecuta en la infraestructura de Anthropic a partir de tu rama de GitHub y sigue en marcha con el portátil cerrado. Envía instrucciones de seguimiento con claude -p "..." --cloud <session-id>.
• Tareas programadas en la nube: se crean con /schedule o en claude.ai/code y se ejecutan según un horario (como máximo una vez por hora), desde una llamada a la API o a partir de eventos de GitHub. Pro, Max, Ultra, Team y Enterprise; vista previa de investigación.
• GitHub Actions: anthropics/claude-code-action@v1 con un disparador schedule. Un token OAuth de claude setup-token usa tu suscripción; una clave de API se factura por token.

Dale a un agente en segundo plano un trabajo fijo

Las tareas en segundo plano, la agent view y cron inician trabajo que ya has decidido tú. Crewmark, en cambio, le da a una sesión de Claude Code un rol continuo: se despierta con un latido (heartbeat) durante su horario, toma la siguiente tarea de un tablero y te escribe cuando se bloquea.

1. Convierte una sesión en un empleado

   Elige un rol y un objetivo en cifras, y ejecuta en Claude Code el comando de configuración que te da Crewmark. Esa conversación se convierte en el empleado.

2. Deja que el latido ponga en marcha el trabajo

   El daemon de Crewmark despierta la sesión cada 15, 30 o 60 minutos durante su horario, con la suscripción que ya pagas, y la deja tranquila fuera de él.

3. Asigna tareas, responde a sus mensajes

   Añade el trabajo como tareas en el tablero; el empleado las toma, comenta sobre la marcha y te pregunta cuando necesita una revisión. Consulta qué es un empleado de IA.

Preguntas frecuentes sobre agentes de Claude Code en segundo plano