Modos de Claude Code: permission modes y formas de arrancar la CLI

Módulo: 3, el framework WAT | Tiempo: unos 25 min de teoría + 20 min de práctica

Lo esencial

Claude Code tiene dos niveles de "modos". El primero es cómo arrancas a Claude (de forma interactiva, con una sola petición, con un pipe). El segundo es cuánto control te guardas mientras trabaja (los permission modes, o modos de permisos).

🎨 Imagínalo así: los modos de arranque son tu forma de llegar a la cocina: puedes entrar y cocinar junto al chef (interactivo), gritar tu pedido por la ventanilla y esperar el platillo listo (print), o mandar los ingredientes por una banda transportadora (pipe). Los permission modes ya son dentro de la cocina: el chef te pregunta antes de cada corte (Manual), corta por su cuenta (Accept edits) o va en piloto automático total (Bypass).

Conceptos clave

Modos de arranque de la CLI: cómo llamar a Claude desde la línea de comandos

• Interactive mode (claude): un REPL en la terminal (la terminal es el programa para trabajar con la línea de comandos), una conversación de ida y vuelta
• Print mode (claude -p "petición"): una pregunta, una respuesta y sale
• Pipe mode (cat file | claude -p "..."): los datos entran por un pipe de Unix
• SDK mode: una llamada programática desde código en Python o TypeScript (lenguajes de programación; TypeScript es JavaScript con tipos)

Permission modes (cuánto control)

• Manual (en la configuración, el valor default, es decir, el valor estándar): Claude pide permiso antes de cada cambio de archivo y de cada comando
• Accept Edits (acceptEdits): Claude edita archivos por su cuenta, pero pregunta antes de los comandos de shell
• Plan Mode (plan): Claude analiza y propone un plan, no cambia nada
• Auto Mode (auto): trabaja sin las preguntas habituales y un modelo clasificador aparte revisa cada acción. Desde la versión 2.1.283 es el modo de arranque predeterminado en la terminal y en VS Code
• Don't Ask (dontAsk): ejecuta solo las acciones aprobadas de antemano y rechaza todo lo demás
• Bypass Permissions (bypassPermissions): ninguna verificación (¡solo en entornos aislados!)
• Shift+Tab: el atajo de teclado para cambiar de modo
• --allowedTools: una lista blanca de herramientas concretas

Teoría

Parte 1: modos de arranque de la CLI

Claude Code se puede arrancar de cuatro formas. Cada una sirve para situaciones distintas.

Interactive mode (predeterminado)

Solo escribe claude en la terminal y se abre una sesión interactiva (REPL). Tú escribes una petición, Claude responde, tú precisas y él ajusta. La conversación sigue hasta que sales (Ctrl+D o /exit).

# Abrir una sesión interactiva
claude

# Abrir con una petición inicial (pero seguimos en la conversación)
claude "explica la estructura de este proyecto"

🎨 Imagínalo así: es como estar sentado a la mesa con un colega. Platican, aclaran y corrigen juntos.

Print mode (una sola petición)

La bandera --print (o su forma corta -p) cambia el comportamiento: Claude recibe la petición, hace el trabajo, escribe la respuesta en stdout y termina el proceso. Sin conversación.

# Una pregunta, una respuesta, y sale
claude -p "Genera un UUID v4 en Python"

# Eligiendo el modelo
claude -p "Explica este código" --model sonnet

🎨 Imagínalo así: como hacer una pregunta por la ventanilla de la caja. Te responden y sigues tu camino.

Pipe mode (cadena de Unix)

Claude Code soporta stdin por completo: puedes pasarle datos con un pipe, como a cualquier herramienta de Unix:

# Analizar un log
cat server.log | claude -p "Encuentra todos los errores ERROR y agrúpalos por tipo"

# Revisión de código con pipe
cat src/payment.py | claude -p "Encuentra vulnerabilidades de seguridad"

# Generar un mensaje de commit a partir del diff
git diff HEAD | claude -p "Escribe un mensaje de commit en formato Conventional Commits"

Limitación: el pipe es práctico para datos pequeños. Para archivos grandes, mejor indica la ruta en la petición.

🎨 Imagínalo así: una banda transportadora en una fábrica. Pones la pieza (los datos) en la banda y a la salida recibes el producto terminado (la respuesta).

SDK mode (llamada programática)

Para desarrolladores existe el Agent SDK: una biblioteca para Python y TypeScript que corre el mismo ciclo de agente que Claude Code. Los nombres de los paquetes y la instalación cambian, así que revisa las instrucciones vigentes en el Agent SDK Quickstart.

El SDK da una respuesta estructurada, callbacks para las llamadas a herramientas y streaming de tokens (los tokens son las unidades mínimas de texto para la IA). Más detalle en la lección Headless Mode y CI/CD y en la documentación de Anthropic.

Parte 2: banderas clave de la CLI

Antes de pasar a los permission modes, estas son las banderas más importantes, que funcionan en cualquier modo:

El modo --bare se recomienda para scripts y CI/CD (Continuous Integration/Delivery: compilación y entrega automáticas). Se salta la carga automática de hooks, skills, subagentes, plugins, servidores MCP, auto memory y CLAUDE.md. Arranca más rápido y da el mismo resultado en cualquier máquina.

Parte 3: Permission Modes (modos de permisos)

Cómo cambiar de modo

• En la terminal (CLI): Shift+Tab recorre en círculo default → acceptEdits → plan. El modo auto entra en el círculo si está disponible; bypassPermissions aparece solo si lo activas aparte (la bandera --allow-dangerously-skip-permissions). El modo actual se ve en la barra de estado debajo del campo de texto.
• En VS Code (un editor de código popular de Microsoft): el indicador de modo en el panel del prompt
• En la app de escritorio: la lista de modos junto al botón de enviar (Cmd+Shift+M); ahí Shift+Tab no funciona
• Al arrancar: la bandera --permission-mode plan (o auto, acceptEdits, dontAsk, bypassPermissions; para el modo Manual, el valor default o el alias manual)
• Por defecto: el ajuste defaultMode en settings.json

Modo 1: Plan Mode

🎨 Imagínalo así: Plan Mode es como un cirujano que antes de operar dice en voz alta todo el plan: "Hago la incisión aquí, luego llego a este vaso, luego...". No es tiempo perdido: es un seguro. Si notas un error en el plan antes de la operación, no tendrás que corregirlo durante.

Qué pasa: Claude analiza la tarea y arma un plan detallado. No ejecuta nada. Espera tu "sí" o tus correcciones.

Ejemplo de salida de Plan Mode:

Contexto: hay que crear un post para LinkedIn
Pasos:
1. Leer voice-samples.md para entender el tono
2. Crear el archivo linkedin-post.md en la carpeta outputs/
3. Escribir un post de 200-250 palabras con un gancho en la primera oración
4. Agregar 3-5 hashtags

Archivos que se crearán: outputs/linkedin-post.md
Archivos que se leerán: context/voice-samples.md

Después de ver el plan eliges: "Yes, and use auto mode" (ejecutar en auto), "Yes, manually approve edits" (revisar cada cambio) o "No, keep planning" (seguir planeando). Si auto no está disponible, la primera opción se llama "Yes, auto-accept edits".

Extra de Plan Mode: puedes agregar comentarios directamente al plan. Por ejemplo, escribir debajo del punto 3 "haz el tono más conversacional": Claude actualiza el plan y lo ejecuta con esa corrección.

Cuándo usarlo:

• Una tarea compleja con varios pasos
• La primera vez que haces algo en un proyecto que no conoces
• Operaciones riesgosas (migración de datos, una refactorización grande, edición masiva de archivos)
• Necesitas explicarle al cliente qué se va a hacer exactamente
• Quieres entender la lógica de Claude antes de que ejecute

Regla práctica: un minuto de planeación ahorra 10 minutos de rehacer. Para cualquier tarea en la que algo pueda salir mal, primero Plan Mode.

Modo 2: Manual (valor default, antes Ask Before Edits)

🎨 Imagínalo así: Manual es como un plomero con experiencia que antes de cada acción te dice: "Voy a cerrar el agua caliente, ¿va?", "Cambio el tubo, mira". Es un poco más lento, pero sin sorpresas.

Nombre: en la interfaz, Manual; en la configuración, el valor default.

Qué pasa: Claude lee los archivos automáticamente, pero antes de cada cambio de archivo o de ejecutar un comando de shell te muestra qué va a hacer y te pide confirmación.

# Arrancar en modo Manual (desde la versión 2.1.283 las sesiones nuevas en la terminal no arrancan en este modo, sino en auto)
claude --permission-mode default

Cuándo usarlo:

• Trabajas en un proyecto en producción donde un error sale caro
• Es la primera vez que trabajas con código ajeno o con un proyecto que no conoces
• Quieres ver cada paso (aprendizaje, auditoría, revisión)
• La tarea toca archivos críticos
• Trabajo delicado con secretos o configuraciones

Cuándo sobra:

• Una tarea rutinaria que ya hiciste muchas veces
• Crear archivos nuevos desde cero (no editar los que ya existen)
• Tareas sencillas de contenido

Modo 3: Accept Edits (en VS Code: Edit automatically)

Nombre oficial: acceptEdits

Qué pasa: Claude crea y edita archivos sin preguntar. También ejecuta automáticamente comandos básicos de archivos (mkdir, touch, mv, cp y similares). Pero los comandos de shell más serios y las peticiones de red siguen pidiendo confirmación.

# Arrancar en modo acceptEdits
claude --permission-mode acceptEdits

Es un modo de trabajo cómodo cuando tú mismo revisas los cambios. Está a un Shift+Tab de Manual.

Cuándo usarlo:

• Una tarea clara con un CLAUDE.md bien configurado
• Tareas que ya hiciste muchas veces
• Escribir textos, crear archivos
• Iteraciones: Claude ya hizo un buen trabajo y le pides que lo mejore

Diferencia con Bypass: Accept Edits todavía pregunta antes de los comandos de shell y las peticiones de red. Bypass nunca pregunta.

Modo 4: Auto Mode (piloto automático vigilado por IA)

Nombre oficial: auto

Qué pasa: Claude trabaja sin pedirte confirmación, pero un modelo de IA aparte (un clasificador de seguridad) revisa cada acción. Si el clasificador ve una acción peligrosa, la bloquea automáticamente. Desde la versión 2.1.283, auto es el modo de arranque predeterminado en la terminal y en VS Code; si auto no está disponible (por el modelo o la configuración de la organización), la sesión arranca en Manual.

# Arrancar en auto mode
claude --permission-mode auto

Requisitos de auto mode:

• Plan: cualquiera (en Team y Enterprise viene activado por defecto y el administrador puede desactivarlo). En Pro también está disponible
• Modelo: uno reciente y compatible; la lista depende del proveedor y cambia con el tiempo. Revisa la documentación de los modos de permisos y la página Lo vigente
• Proveedor: la Anthropic API (Application Programming Interface, la interfaz de programación de aplicaciones), y también Amazon Bedrock, Google Cloud Agent Platform y Microsoft Foundry

Qué bloquea el clasificador por defecto:

• Descargar y ejecutar código (curl | bash; bash es el lenguaje de comandos de la terminal de Unix)
• Deploy (publicar en producción) a producción
• Borrado masivo de archivos
• Force push y push a main
• Enviar datos a servidores externos

Cuándo usarlo:

• Tareas largas en las que ya te cansaste de apretar "Yes" cada 10 segundos
• Confías en la dirección del trabajo pero quieres una red de seguridad
• Necesitas velocidad pero no estás listo para un Bypass total

🎨 Imagínalo así: el piloto automático de un Tesla. El coche maneja solo, pero el sistema vigila el camino y frena si ve un obstáculo. No es perfecto, pero es mucho mejor que manejar con los ojos cerrados.

Modo 5: Don't Ask (solo lo aprobado de antemano)

Nombre oficial: dontAsk

Qué pasa: Claude puede ejecutar ÚNICAMENTE las acciones que aprobaste de antemano en las reglas (permissions.allow). Todo lo demás se rechaza automáticamente, sin preguntar. Es totalmente no interactivo.

# Arrancar en modo dontAsk
claude --permission-mode dontAsk

Cuándo usarlo:

• Pipelines de CI/CD donde no hay una persona presente
• Necesitas un control estricto de qué está permitido exactamente
• Conoces de antemano todo el conjunto de operaciones

Modo 6: Bypass Permissions

Nombre oficial: bypassPermissions

Qué pasa: Claude recibe autonomía total. Ninguna confirmación, ningún clasificador, ninguna pausa. Hace TODO lo que considere necesario. Incluso la escritura en rutas protegidas (.git/, la carpeta de git, el sistema de control de versiones del código; .vscode/ y otras) pasa sin preguntas.

Cómo activarlo:

# Desde la CLI
claude --permission-mode bypassPermissions

# Forma corta (el mismo efecto)
claude --dangerously-skip-permissions

En VS Code: Settings → busca "allow dangerously" → activa la opción. Después de eso, Bypass aparece en el menú de modos.

Cuándo usarlo:

• Contenedores aislados, máquinas virtuales, dev containers sin acceso a internet
• Pipelines de CI/CD en un entorno sandbox
• Ya revisaste el plan en Plan Mode y quieres ejecutarlo sin interrupciones

Cuándo NO usarlo:

• En tu computadora principal
• Con código que no conoces
• En un entorno de producción

El esquema Plan → ejecución (recomendado):

1. Recibí una tarea compleja
2. La corrí en Plan Mode → revisé el plan → agregué correcciones
3. Aprobé el plan → Claude propone:
   - Yes, and use auto mode
   - Yes, manually approve edits
   - No, keep planning
4. Elegí el nivel adecuado → ejecución

Advertencia: Bypass no protege contra prompt injection ni contra acciones no intencionales. Si necesitas autonomía CON seguridad, usa Auto Mode.

🎨 Imagínalo así: Bypass es como darle las llaves del coche a un conductor con los ojos vendados. Auto Mode es como darle las llaves con un sistema de frenado que funciona. La primera opción, solo en una pista cerrada (un contenedor).

allowedTools: lista blanca de herramientas

La bandera --allowedTools te deja permitir de forma puntual herramientas concretas durante un solo arranque, sin abrir un Bypass completo.

Uso en la CLI:

claude --allowedTools "Read,Write,Bash(git commit*)" "haz commit de todos los cambios"

Qué te da:

• Control fino: permitir solo leer archivos, no escribirlos
• Permitir solo operaciones de git, no comandos del sistema
• Permitir web-fetch pero no la edición de archivos

Ejemplo práctico, una rutina nocturna:

claude --allowedTools "Read,Bash(curl*)" --print \
  "corre la verificación de salud de la API y guarda un reporte"

Tabla comparativa de los permission modes

Escenarios típicos de cambio de modo

Escenario 1: primer contacto con una tarea

Plan Mode → revisa el plan → apruébalo → Accept Edits o Auto Mode

Escenario 2: una tarea sencilla en un proyecto limpio

Accept Edits (acceptEdits) → suficiente

Escenario 3: una operación riesgosa en producción

Plan Mode → revisa el plan → agrega correcciones → Manual para la ejecución

Escenario 4: pipeline de CI/CD

# Opción A, control estricto:
claude -p "..." --permission-mode dontAsk --allowedTools "Read,Bash(git *)"

# Opción B, autonomía total dentro de un contenedor:
claude -p "..." --dangerously-skip-permissions --max-turns 5

Escenario 5: una tarea larga con muchos archivos

Plan Mode → asegúrate de que la lista de archivos es correcta → Auto Mode

Escenario 6: continuar el trabajo de ayer

# Continuar la última conversación
claude --continue

# Retomar una sesión concreta por su nombre
claude --resume "auth-refactor"

Los modos como manejo de riesgo

🎨 Imagínalo así: los modos son como la velocidad en el camino. En la zona escolar, 20 km/h. En la carretera, 120. En una autopista sin límite, 180. No vas igual en todas partes: eliges la velocidad según las condiciones. Bypass en producción es como ir a 180 en una zona escolar.

Los modos no son una comodidad, son manejo de riesgo. La regla es simple:

Entre más alto lo que está en juego, más control.

¿Corregir una errata en un texto? Accept edits. ¿Borrar una carpeta con datos de un cliente? Plan Mode + Manual + lee el plan tres veces.

Lo que está en juego se define con dos preguntas:

1. ¿Qué tan irreversible es si algo sale mal?
2. ¿Qué tan caro es corregir el error?

Práctica

Tarea: recorrer todos los modos con una misma tarea

Toma una tarea: "Crea el archivo outputs/test-post.md con un post corto sobre los beneficios de la IA para pequeños negocios, de 100-150 palabras."

1. Plan Mode: corre la tarea y revisa el plan. Agrega el comentario "haz el tono más conversacional". Aprueba el plan actualizado
2. Accept edits: pídele a Claude "agrega tres hashtags al final del post" y mira cómo lo hace sin preguntar
3. Manual: pide "cambia el título del post" y mira cómo Claude muestra el diff y pide permiso
4. Activa Bypass Permissions en la configuración y pide "crea una copia del archivo con el nombre test-post-v2.md": mira cómo lo hace sin pausas
5. Corre /context y mira cuántos tokens se fueron en todo esto

Objetivo: sentir en la práctica, no en teoría, la diferencia entre los modos. Después de esto, cambiar de modo será un reflejo.

Herramientas y recursos

• Shift+Tab: el atajo para cambiar de permission mode
• --permission-mode: la bandera de la CLI para elegir el modo al arrancar
• --allowedTools: lista blanca de herramientas (acepta comodines: "Bash(git *)")
• --disallowedTools: lista negra de herramientas
• -p / --print: arrancar sin modo interactivo (print mode)
• -c / --continue: continuar la última conversación
• -r / --resume: retomar una sesión concreta
• --model: elegir el modelo (sonnet, opus, haiku, fable o el nombre completo)
• --bare: arranque rápido sin cargar contexto (para scripts)
• --max-turns: límite de iteraciones en print mode
• --max-budget-usd: tope de gasto en dólares
• Documentación: CLI reference y modos de permisos

Ideas clave

4 formas de arrancar: Interactive (conversación), Print -p (una petición), Pipe (datos de entrada), SDK (desde código). Para automatizar, print + pipe. Para trabajar a mano, interactive.

6 permission modes: desde el control máximo (Plan/Default) hasta ninguno (Bypass). Auto Mode es el punto medio: autonomía con una red de seguridad de IA. Accept Edits es el caballo de batalla de todos los días.

Plan Mode es un seguro que no cuesta nada. Un minuto de plan ahorra una hora de correcciones. Después de aprobar el plan, Claude te propone en qué modo ejecutarlo.

Bypass, solo para contenedores. Si necesitas autonomía en una máquina real, usa Auto Mode. Bypass no te protege de nada.

--bare para scripts. Cuando Claude arranca desde un script o desde CI, agrega --bare para que no cargue contexto de más. Más rápido y más predecible.

Siguiente lección

→ Tokens y ventana de contexto: los tokens, la ventana de contexto y la economía de cada petición