Tutorial: Tu primera tarea real
Primeros pasos te dejó instalado y chateando en cinco minutos. Este tutorial es el siguiente paso: un recorrido práctico por lo que ADHDev sirve realmente — ejecutar un agente de codificación real, mantener el control de lo que hace y (opcionalmente) coordinar el trabajo entre máquinas a través de Repo Mesh y dejar que la Refinery lo aterrice en main.
Harás todo a mano para poder ver funcionar cada pieza. Al final entenderás las cuatro cosas que ADHDev te ofrece — Refinery, cualquier agente, tus máquinas, control remoto — no como viñetas, sino por haberlas conducido.
Lo que necesitas
- El CLI
adhdevinstalado (consulta Primeros pasos si no). - Al menos un agente CLI instalado y autenticado en tu máquina — Claude Code, Codex CLI, Gemini CLI u otro. ADHDev no gestiona el inicio de sesión propio del agente; el agente mantiene su propia autenticación.
- Un repositorio git en el que te sientas cómodo dejando que un agente haga un pequeño cambio.
Todo este tutorial funciona en modo Standalone (sin cuenta). La sección de Repo Mesh al final es solo Cloud — está marcada claramente, y todo lo anterior es autónomo.
Paso 1 — Inicia standalone y abre el panel
adhdev standaloneEsto inicia juntos el daemon embebido (localhost:3847) y el panel local (localhost:3000). Abre http://localhost:3000.
Lo que verás: el panel con tu máquina local listada como online. Sin pantalla de inicio de sesión — standalone es totalmente local.
📸 [captura de pantalla: panel standalone, una máquina online, lista de sesiones vacía]
Por qué importa: este es el plano de control. Todo lo que un agente haga a partir de aquí — chat, llamadas de herramientas, aprobaciones — fluye peer-to-peer entre este navegador y tu daemon. El panel es tu vista única sobre cada sesión, y en un momento tendrá una que mostrar.
Comprobación de cordura
Si el panel está vacío o la máquina aparece offline, ejecuta adhdev doctor en otra terminal. Revisa el proceso del daemon, la conexión local y el registro de proveedores, y señala la corrección específica.
Paso 2 — Mira lo que ADHDev puede conducir
Antes de lanzar, mira lo que se detecta en esta máquina:
adhdev detectLo que verás: una lista de proveedores conocidos con installed: yes/no. Cualquier yes está listo para lanzarse.
Por qué importa: un proveedor es el adaptador de ADHDev para un agente, y hay cuatro tipos — aquí elegirás del primero:
| Categoría | Transporte | Ejemplos |
|---|---|---|
| cli | PTY (terminal) | Claude Code, Codex CLI, Gemini CLI, Hermes CLI |
| ide | Chrome DevTools Protocol | Cursor, VS Code, Windsurf, Kiro, PearAI, Trae |
| extension | CDP webview | Antigravity |
| acp | stdio (Agent Client Protocol) | Agentes compatibles con ACP |
Para este tutorial usamos un proveedor cli — es el más rápido para llegar a una sesión funcional y no necesita relanzar el editor.
Paso 3 — Lanza una sesión de agente CLI
Elige un agente CLI que mostró installed: yes. Por ejemplo:
adhdev launch claude # Claude Code
# or: adhdev launch codex / adhdev launch geminiEl daemon inicia el agente bajo un PTY y transmite la terminal al panel.
Lo que verás: aparece una nueva tarjeta de sesión en el panel. Haz clic en ella para abrir una vista de terminal en vivo con una casilla de entrada en la parte inferior.
📸 [captura de pantalla: tarjeta de sesión + vista de terminal abierta con casilla de entrada]
Por qué importa: el agente se ejecuta en tu máquina, en tu directorio de trabajo, con su propia autenticación — ADHDev simplemente te da una ventana hacia él. Nada del comportamiento del agente cambió; has añadido un plano de control encima.
Directorio de trabajo
La sesión se ejecuta en el directorio desde el que la lanzaste. Apúntala al repo git en el que quieres que trabaje el agente — o haz cd allí antes de adhdev launch, o abre el repo desde el flujo de lanzamiento en el panel.
Paso 4 — Chatea y mantén el control de las aprobaciones
En la casilla de entrada de la sesión, pídele al agente que haga algo pequeño y real. Por ejemplo:
Mira este repo y añade una descripción de una línea en la parte superior del README que explique qué hace.
Escríbelo y presiona Enter, exactamente como lo harías en la terminal local.
Lo que verás:
- La respuesta del agente se transmite al panel en tiempo real — los mismos tokens que verías en la terminal local.
- Cuando el agente quiere ejecutar una herramienta o editar un archivo, aparece un banner ACTION REQUIRED con botones Approve y Reject.
📸 [captura de pantalla: banner de aprobación ACTION REQUIRED con Approve / Reject]
Haz clic en Approve para dejar pasar la edición (o Reject para rechazarla). La decisión viaja por el canal peer-to-peer al daemon, y el agente continúa.
Por qué importa: esto es el control human-in-the-loop. El agente nunca ejecuta silenciosamente un comando que no viste — cada llamada de herramienta y edición de archivo emerge como una aprobación que tú posees. Ese mismo banner es lo que te permite alejarte del teclado y seguir al mando, que es exactamente sobre lo que se construye el siguiente paso.
Adjuntar una imagen
La entrada de chat acepta adjuntos de imagen (hasta 5 imágenes, 10 MB cada una) — útil para pegar una captura de pantalla de un bug o un diseño que quieres que el agente reproduzca.
Paso 5 — Aprueba desde tu teléfono (Cloud)
Solo en la nube
Este paso necesita la versión Cloud. Standalone es de máquina única y solo local, por lo que no hay una superficie remota desde la que aprobar. Si estás en standalone, salta a Próximos pasos — ya has visto el bucle principal.
El banner de aprobación del Paso 4 no está atado a la máquina en la que se ejecuta el agente. En modo nube, inicia sesión en el navegador de tu teléfono en adhf.dev y el mismo banner Approve / Reject aparece allí — diseño responsivo, mismo flujo de aprobación peer-to-peer.
📸 [captura de pantalla: banner de aprobación móvil]
Lo que verás: un agente se pausa en una llamada de herramienta en tu escritorio; la aprobación aparece en tu teléfono; tocas Approve; el agente continúa.
Por qué importa: puedes iniciar trabajo de larga duración y alejarte. El agente se detiene y espera a ti en cada punto de decisión, dondequiera que estés. (Los teléfonos reciben y responden aprobaciones; despachar nuevas tareas sigue siendo una acción de escritorio/CLI.)
Paso 6 — Coordina entre máquinas con Repo Mesh (Cloud)
Solo en la nube
Repo Mesh coordina varios daemons de la misma cuenta y está disponible solo en la versión Cloud. Es la capa por encima de un solo panel — donde un coordinador entrega trabajo a agentes en muchas máquinas (o muchos worktrees aislados) y converge los resultados. Consulta la guía completa de Repo Mesh para los conceptos; aquí solo configuramos uno.
Hasta ahora has conducido un agente en una sesión. Repo Mesh es lo que convierte eso en una persona coordinando muchos agentes. Aquí está la versión de extremo a extremo más pequeña.
1. Crea un mesh para tu repo. Desde dentro del repo (para que el remote de git se detecte automáticamente):
adhdev mesh create my-project --add-current--add-current también registra tu workspace actual como el primer nodo del mesh. El comando imprime un ID de mesh (p. ej. mesh_abc123).
Lo que verás: una confirmación con el ID del mesh, la identidad del repo detectada y la rama, seguida de pistas de "Próximos pasos".
2. Añade otro nodo. En una segunda máquina (o como un worktree aislado), añádela al mismo mesh. Un worktree evita que los agentes en paralelo pisen el árbol de trabajo del otro:
adhdev mesh add-node mesh_abc123 --worktree --provider-priority claude-cli,codex-cli--provider-priority le dice al nodo qué agente lanzar cuando una tarea no nombra uno — un nodo sin prioridad establecida se negará a auto-lanzar en lugar de adivinar.
3. Confirma la forma del mesh.
adhdev mesh show mesh_abc123 # nodes, policy, per-node launch readiness
adhdev mesh status mesh_abc123 # live per-node git health (branch, dirty, ahead/behind)📸 [captura de pantalla: salida de adhdev mesh status, nodos con rama + estado limpio/sucio]
Por qué importa: ahora tienes más de un workspace inscrito bajo un coordinador. Desde la página Repo Mesh del panel de la nube (/mesh), encolas tareas contra una misión, y los nodos inactivos extraen el trabajo de forma autónoma — Claude Code en un nodo, Codex en otro. No empujas una tarea a una máquina específica y la cuidas; los nodos rápidos e inactivos vacían la cola, y el coordinador vigila los eventos de finalización en lugar de sondear. Cada tarea se mueve pending → assigned → completed (o failed).
Paso 7 — Deja que la Refinery aterrice el trabajo (Cloud)
Solo en la nube
La Refinery se ejecuta como parte de la convergencia de Repo Mesh.
Generar agentes en paralelo es la parte fácil. Fusionar lo que producen es la parte difícil — y esta es la parte para la que existe ADHDev.
Cuando una tarea termina en una rama de worktree aislada, la Refinery converge esa rama de vuelta a su base sin un force-push, nunca. Ejecuta una secuencia de puertas: carga la configuración de convergencia del repo, arranca el worktree, ejecuta la validación propia de tu repo (typecheck / tests / lint), aplica un no-op guard y una comprobación de equivalencia de parches, publica cualquier commit de submódulo, hace un merge solo fast-forward en la base y limpia el worktree.
Cada rama tocada aterriza en exactamente un estado final, para que nada quede silenciosamente en una rama perdida:
| Estado final | Significado |
|---|---|
merged_to_main | Convergido y fusionado limpiamente. |
pushed_feature_branch_needs_merge | Pusheado, esperando un merge que harás tú. |
blocked_review | Retenido para un humano — p. ej. commits de submódulo aún no accesibles desde el origin del submódulo. |
cleanup_candidate | El trabajo está aterrizado; el worktree puede eliminarse. |
not_mergeable | No se puede hacer fast-forward. La Refinery se niega y te pide a ti en lugar de resolver un conflicto a ciegas. |
📸 [captura de pantalla: log de convergencia de la Refinery terminando en merged_to_main]
Por qué importa: esta es la diferencia entre "diez agentes se ejecutaron" y "diez ramas aterrizaron de forma segura." La Refinery es git-native y conservadora a propósito — valida contra tus puertas y solo hace fast-forward. Cualquier cosa que no pueda aterrizar limpiamente (un conflicto real, un commit de submódulo inaccesible) vuelve a ti como not_mergeable o blocked_review, no un merge silencioso. Obtienes paralelismo sin la resaca del día del merge.
Lo que acabas de hacer
Ejecutaste un agente real a través de ADHDev y mantuviste el control todo el camino:
- Control remoto + HITL — condujiste una sesión en vivo desde el panel y aprobaste cada llamada de herramienta (desde tu teléfono, en modo nube).
- Cualquier agente — lanzaste un agente CLI a través de un adaptador de proveedor; el mismo flujo funciona para Codex, Gemini, IDEs sobre CDP y agentes ACP.
- Tus máquinas — el agente se ejecutó en tu propio hardware, con su propia autenticación, bajo tu panel.
- Refinery — (nube) inscribiste nodos en un mesh y viste cómo el trabajo terminado converge a
maina través de puertas de validación, con un estado final claro para cada rama.
Próximos pasos
- Repo Mesh — el modelo completo: misiones, cola, ledger y la Refinery en profundidad.
- Multimáquina — vincular portátil, escritorio y máquina de trabajo bajo una cuenta.
- Servidor MCP — exponer sesiones de ADHDev (y coordinación de mesh) como herramientas a otro agente.
- Agentes CLI — gestionar sesiones PTY, scrollback y reinicios.
- Panel — paneles, el conmutador de máquinas y compartir sesiones.
- Móvil — el panel responsivo y el flujo de aprobación en un teléfono.
- Compatibilidad y advertencias — qué está verificado vs. experimental.