Cómo usar Aider: guía paso a paso

Para usar Aider, instálalo con aider-install o con el script de una línea, entra con cd en un repositorio git, arráncalo con aider --model sonnet --api-key anthropic=<key> (u otro proveedor), añade con /add los archivos que quieres cambiar y describe el cambio en lenguaje natural. Aider edita los archivos y hace commit de cada cambio en git, así que /undo lo deshace.

Ese es todo el ciclo. Esta guía cubre lo que hace que Aider sea cómodo de usar: API keys y modelos, qué archivos añadir, los modos ask, code y architect, los formatos de edición, el comportamiento con git, .aider.conf.yml, la integración con lint y tests y un archivo de convenciones. Todos los comandos y flags de esta guía salen de la documentación oficial de Aider en aider.chat a octubre de 2026.

Qué es Aider

Aider es un programador en pareja con IA para la terminal. Es un agente de programación que funciona con casi cualquier LLM: Claude, GPT, Gemini, DeepSeek o un modelo local. Dos cosas lo distinguen de la mayoría de agentes CLI. Primero, está construido alrededor de git: cada edición se convierte en un commit. Segundo, es explícito con el contexto: tú decides qué archivos están en el chat, y un mapa del repositorio le da al modelo un resumen del resto.

Si lo estás comparando con otros agentes de terminal, cómo usar opencode y cómo usar GitHub Copilot CLI siguen el mismo formato paso a paso.

Paso 1: instala Aider

La documentación de Aider recoge varias formas de instalarlo. Elige una.

aider-install instala Aider en su propio entorno de Python, así que no choca con los paquetes de tu proyecto. Si lo instalas con pip a secas, hazlo dentro de un entorno virtual. Si después de instalar con pip no se encuentra el comando aider, python -m aider hace lo mismo.

Paso 2: API keys y modelos

Aider se comunica con los proveedores de modelos usando tus propias keys. La forma más rápida de empezar es pasar el modelo y la key en la línea de comandos:

cd /to/your/project

# Anthropic
aider --model sonnet --api-key anthropic=<key>

# OpenAI
aider --model o3-mini --api-key openai=<key>

# DeepSeek
aider --model deepseek --api-key deepseek=<key>

Escribir la key cada vez acaba cansando. Aider también lee las variables de entorno habituales (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, DEEPSEEK_API_KEY, etc.) y un archivo .env en tu proyecto. --api-key proveedor=<key> funciona con cualquier proveedor: --api-key gemini=xxx fija GEMINI_API_KEY.

Los nombres cortos como sonnet son alias integrados. A octubre de 2026, la documentación asocia sonnet, opus y haiku a los modelos actuales de Claude, gemini y flash a modelos de Gemini, deepseek y r1 a DeepSeek chat y reasoner, y 4o a GPT-4o. Puedes definir los tuyos:

aider --alias "fast:gpt-4o-mini" --model fast

Dentro de una sesión, /model <nombre> cambia el modelo principal, /models <búsqueda> lista los modelos disponibles y /reasoning-effort fija el esfuerzo en los modelos que lo admiten. Aider también usa un “modelo débil” más barato para los mensajes de commit y los resúmenes del chat; --weak-model lo cambia. ¿Quieres ejecutarlo en tu propio hardware? La guía de agentes de programación con LLM local explica esa configuración.

Paso 3: añade archivos al chat

Aider solo edita los archivos que están en el chat. Puedes nombrarlos al arrancar:

aider src/api/users.py tests/test_users.py

o añadirlos más tarde:

/add src/api/users.py tests/test_users.py

La documentación de Aider es clara en un punto: añade solo los archivos que hay que editar para la tarea. Cada archivo que añades cuesta tokens, y demasiados archivos pueden saturar al modelo. Aider construye un mapa de todo el repositorio, así que el modelo ya sabe dónde están las funciones y clases relacionadas sin que tengas que añadirlas. Si no añades nada, Aider intenta averiguar qué archivos hay que editar.

Los comandos que gestionan el contexto:

• /add <archivos> añade archivos que Aider puede editar.
• /read-only <archivos> añade archivos de referencia que puede leer pero no cambiar (documentación, un módulo de ejemplo).
• /drop <archivos> quita archivos para liberar contexto; /drop a secas los quita todos.
• /ls lista los archivos del chat y del repositorio.
• /tokens muestra cuántos tokens usa el contexto actual.
• /map imprime el mapa del repositorio y /map-refresh lo reconstruye.

Después describe el cambio:

Añade paginación al endpoint list_users: acepta los parámetros de consulta
page y page_size, usa 20 por página por defecto y actualiza los tests.

Paso 4: los modos ask, code y architect

Aider tiene modos de chat, y elegir el adecuado es la mayor parte del oficio.

/ask, /code y /architect seguidos de un mensaje se aplican solo a ese mensaje. Escritos solos, cambian el modo hasta que vuelvas a cambiarlo; /chat-mode <modo> hace lo mismo. --chat-mode <modo> elige el modo al arrancar, y --architect es un atajo.

El flujo que recomienda la documentación es alternar. Primero pregunta, afina el plan y luego deja que programe:

/ask ¿Cómo debería añadir rate limiting a la ruta de login sin tocar
los demás endpoints? No cambies nada todavía.

Cuando el plan te convenza, escribe /ok. Es un atajo de “/code Ok, please go ahead and make those changes.” (“vale, adelante, haz esos cambios”).

El modo architect reparte el trabajo entre dos modelos. El modelo principal describe cómo resolver el problema, y un modelo editor, que se fija con --editor-model, lo convierte en ediciones de archivos. Si no eliges uno, Aider escoge un modelo editor razonable para cada modelo principal. Esto suele ayudar con los modelos de razonamiento, que planifican bien pero son menos fiables al producir ediciones exactas. La contrapartida: el modo architect envía dos peticiones por cambio, así que es más lento y cuesta más.

Paso 5: formatos de edición

Un formato de edición es la manera en que el modelo le dice a Aider qué cambiar. Rara vez tendrás que tocarlo, porque Aider elige el mejor formato para cada modelo, pero conviene saber qué estás viendo:

Cámbialo con --edit-format <formato> y fija el formato del modelo editor con --editor-edit-format. Si un modelo produce una y otra vez ediciones que no se aplican, pasarlo a whole es una prueba razonable con archivos pequeños.

Paso 6: git, commits automáticos y /undo

Aider funciona mejor dentro de un repositorio git. Por defecto:

• Cada edición que hace Aider se guarda en un commit con un mensaje descriptivo, escrito por el modelo débil al estilo Conventional Commits.
• Si tenías cambios sin commit en archivos antes de que Aider los edite, primero hace commit de esos, para que tu trabajo y el suyo queden en commits separados.
• Se añade “(aider)” al nombre de autor y de committer de git en sus commits.

Eso hace que la red de seguridad sea sencilla:

• /diff muestra los cambios desde tu último mensaje.
• /undo revierte el último commit si lo hizo Aider.
• /commit hace commit de las ediciones externas que hiciste tú.
• /git <comando> ejecuta cualquier comando de git sin salir del chat.

Puedes desactivar partes de esto: --no-auto-commits deja las ediciones sin commit para que las revises, --no-dirty-commits se salta el commit previo a la edición y --no-git desactiva git por completo (la documentación lo desaconseja). Aider hace commit con --no-verify por defecto, así que tus hooks de pre-commit no se ejecutan; añade --git-commit-verify si quieres que se ejecuten. Si prefieres mantener los cambios de Aider lejos de tu copia principal, ejecútalo en un git worktree aparte.

Paso 7: configura .aider.conf.yml

Los flags que usas siempre van en un archivo YAML. Aider carga .aider.conf.yml desde tu carpeta de inicio, luego desde la raíz del repositorio git y luego desde la carpeta actual; los últimos prevalecen. --config <archivo> carga solo ese archivo.

# .aider.conf.yml
model: sonnet
weak-model: haiku
auto-commits: true
dirty-commits: true
lint-cmd: "python: ruff check --fix"
test-cmd: pytest -q
auto-test: false
read: [CONVENTIONS.md]

Las claves del archivo coinciden con los nombres largos de los flags sin los guiones. Las API keys también pueden ir aquí (anthropic-api-key:, openai-api-key: o una lista api-key: como - gemini=xxx), pero en ese caso deja el archivo fuera de git. Por defecto, Aider añade .aider* a .gitignore para que sus archivos de historial no acaben en los commits.

Paso 8: integración con lint y tests

Aider pasa el linter a los archivos que edita justo después de cada cambio, con linters integrados para la mayoría de lenguajes populares. Si el linter encuentra problemas, Aider intenta corregirlos. Puedes usar tu propio linter:

aider --lint-cmd "python: ruff check --fix" --lint-cmd "javascript: npx eslint --fix"

El comando tiene que imprimir los errores y salir con un código distinto de cero cuando encuentra problemas. --no-auto-lint desactiva el lint.

Los tests funcionan igual, pero están desactivados por defecto. Fija un comando con --test-cmd y activa --auto-test, y Aider ejecutará los tests después de cada cambio e intentará corregir los fallos (cualquier código de salida distinto de cero). En el chat:

• /lint pasa el linter y corrige los archivos del chat, o todos los archivos modificados si no has añadido ninguno.
• /test <comando> ejecuta un comando y, si falla, añade la salida al chat.
• /run <comando> (o !<comando>) ejecuta un comando de shell y te deja compartir su salida.

Paso 9: un archivo de convenciones

Aider no tiene un archivo de instrucciones de proyecto integrado que cargue por sí solo. El método documentado es un archivo Markdown normal que cargas en solo lectura:

# CONVENTIONS.md
- Prefer httpx over requests for making http requests.
- Use types everywhere possible.
- Every new endpoint needs a test in tests/api/.

aider --read CONVENTIONS.md

o /read-only CONVENTIONS.md durante una sesión, o read: CONVENTIONS.md en .aider.conf.yml para que se cargue siempre. Los archivos de solo lectura se guardan en caché cuando el prompt caching está activado, así que el coste se mantiene bajo. Si ya tienes un AGENTS.md para otros agentes, puedes cargar ese; CLAUDE.md y AGENTS.md da consejos para escribir reglas que los agentes de verdad sigan.

Dos funciones más que conviene conocer

Scripts. --message (o -m) envía una instrucción, aplica las ediciones y termina, lo que facilita recorrer archivos en un bucle:

for FILE in *.py ; do
  aider --message "add descriptive docstrings to all the functions" $FILE
done

Añade --yes-always para aceptar las confirmaciones automáticamente, y --message-file para leer la instrucción desde un archivo.

Modo watch. Arranca Aider con --watch-files y sigue trabajando en tu editor. Escribe un comentario que termine en AI! y Aider hace el cambio; termínalo en AI? y Aider responde la pregunta. Funciona con comentarios #, // y --.

Errores habituales

• Añadir todo el repositorio. Más archivos significan más coste y peores ediciones. Añade lo que cambia, usa /read-only para las referencias y confía en el mapa del repositorio.
• Olvidar el commit de cambios pendientes. Aider hace commit de tus ediciones pendientes antes de tocar un archivo. Si eso te sorprende, haz commit o stash antes, o usa --no-dirty-commits.
• Esperar que se ejecuten los hooks. Los commits se saltan los hooks de pre-commit a menos que pases --git-commit-verify.
• Usar el modo architect para todo. Duplica las peticiones. Úsalo para los cambios complicados; el modo code normal basta para ediciones pequeñas.
• Keys en una configuración con commit. Si .aider.conf.yml contiene API keys, guárdalo en tu carpeta de inicio o fuera de git.
• Chats largos. Los mensajes antiguos cuestan tokens en cada petición. /clear borra el historial del chat y /reset además quita los archivos.

Aider en AgentVera

AgentVera es una app de escritorio para macOS, Windows y Linux que ejecuta agentes CLI uno al lado de otro en terminales reales, con tus propias instalaciones y keys. Aider es uno de los agentes que admite; la página de Aider en AgentVera tiene los detalles:

• Tus keys, tu configuración. Aider lee las keys de los proveedores desde las variables de entorno o desde .aider.conf.yml, como siempre. El modelo que eliges en AgentVera se pasa con --model, y el esfuerzo bajo, medio o alto con --reasoning-effort.
• Historial separado por agente. Cada agente Aider tiene su propio archivo de historial de chat en ~/.aider/agentvera/ y lo continúa con --restore-chat-history cuando se vuelve a abrir la app, así que varios agentes Aider nunca mezclan sus historiales.
• Roles como archivo de solo lectura. Aider no permite ampliar su prompt de sistema, así que el rol del agente se pasa con --read, el mismo mecanismo que un archivo de convenciones.
• Paneles junto a otros agentes. Ejecuta Aider en la cuadrícula del workspace junto a Claude Code o Codex, y arranca agentes en sus propios worktrees desde el panel Git.
• Revisión y flujos. Los agentes Aider reciben revisión de código automática al terminar cada turno, y funcionan en flujos (Pro y Team), envíos a varios agentes y tareas programadas.

Un límite que conviene saber: los servidores MCP que configuras en AgentVera no se pasan a Aider. La cuadrícula, los worktrees y la revisión de código están en el plan gratuito. Descarga AgentVera para probarlo.

Conclusión

Instala Aider, entra con cd en un repositorio git, arráncalo con un modelo y una key, y añade solo los archivos que necesita el cambio. Usa /ask para planificar y /ok o /code para aplicar, prueba /architect con los problemas más difíciles y apóyate en /diff y /undo, porque cada edición es un commit. Pon tus valores por defecto en .aider.conf.yml, tus reglas en CONVENTIONS.md, y deja que --lint-cmd y --test-cmd detecten los errores antes que tú. Si también usas el agente de GitHub, cómo usar GitHub Copilot CLI es la misma guía para esa herramienta.