La mayoría de los desarrolladores que ejecutan múltiples agentes de IA se topan con el mismo muro alrededor del agente número cinco. Tienes a Claude Code en un terminal reescribiendo un servicio de backend, Codex en otro generando pruebas, Cursor editando un componente y tres pestañas más que olvidaste revisar. Nadie sabe lo que hace el otro. Los costos se disparan. Dos agentes duplican el mismo trabajo. Uno funciona durante seis horas y no produce nada útil porque nadie le dio un objetivo claro.
Paperclip soluciona esto. Es una plataforma de orquestación de código abierto que convierte tus agentes de IA dispersos en una empresa estructurada, con organigramas, roles asignados, gestión de tareas, límites de presupuesto y registros de auditoría. Alcanzó más de 35,000 estrellas en GitHub en menos de tres semanas, lo que demuestra cuántos desarrolladores compartían la misma frustración.
Este artículo te guiará a través de su configuración, la estructuración de tu primera empresa de agentes y su ejecución para que el trabajo se realice sin que tengas que supervisar cada terminal.
Qué es Paperclip (y qué no es)
Antes de instalar cualquier cosa, comprende lo que estás obteniendo.
Paperclip es una capa de orquestación. Coordina agentes, rastrea su trabajo, controla sus presupuestos y les da contexto sobre los objetivos de la empresa. No construye agentes, no reemplaza a tu proveedor de IA ni añade una interfaz de chat.
El modelo mental que utiliza el equipo de Paperclip: "Si Claude Code es un empleado, Paperclip es la empresa".
Eso significa que:
- Los agentes tienen roles, no solo instrucciones (prompts)
- Las tareas tienen propietarios, no solo terminales abiertos
- Los presupuestos tienen límites estrictos, no solo "buenas vibraciones"
- Todo se registra en un registro de auditoría
Paperclip funciona con Claude Code, OpenAI Codex, Cursor, Gemini CLI y cualquier agente que pueda recibir un webhook o una señal de latido. Tú traes los agentes. Paperclip dirige la empresa.
Explícitamente no es:
- Una interfaz de chatbot
- Un constructor de flujos de trabajo de arrastrar y soltar como n8n o Zapier
- Un framework para escribir agentes
- Útil para casos de uso de un solo agente
Si ejecutas un solo agente de IA ocasionalmente, Paperclip es excesivo. Si ejecutas tres o más agentes en un trabajo continuo, es la pieza que falta.
Instalando Paperclip
Necesitas Node.js 20+, pnpm 9.15+ y eso es todo. Paperclip se envía con una base de datos PostgreSQL incrustada, por lo que no necesitas configurar almacenamiento externo.
La forma más rápida de empezar:
npx paperclipai onboard --yes
Esto descarga la CLI, ejecuta la configuración inicial con valores predeterminados sensatos y inicia el servidor en el puerto 3100. Abre http://127.0.0.1:3100 y estarás viendo el panel de control.
Si quieres contribuir o profundizar en el código:
git clone https://github.com/paperclipai/paperclip.git
cd paperclip
pnpm install
pnpm dev
Si prefieres Docker:
docker compose -f docker-compose.quickstart.yml up --build
Qué se crea en el disco:
Paperclip almacena todo en ~/.paperclip/instances/default/:
~/.paperclip/instances/default/
config.json — configuración del servidor y almacenamiento
db/ — archivos de datos de PostgreSQL incrustados
secrets/master.key — clave de cifrado (autogenerada)
logs/ — registros del servidor
data/storage/ — archivos adjuntos
workspaces/<agent>/ — directorios de trabajo por agente
El modo local utiliza autenticación `local_trusted` por defecto, lo que omite el inicio de sesión y utiliza un usuario sintético "Board". Puedes empezar a usar el panel de control inmediatamente, no se necesita crear una cuenta.
Una vez dentro, ejecuta la comprobación de estado:
paperclipai doctor
Si algo está mal configurado, `--repair` soluciona la mayoría de los problemas automáticamente:
paperclipai doctor --repair
Configurando tu primera empresa
En Paperclip, una "empresa" es el contenedor de nivel superior para tus agentes, tareas, objetivos y presupuestos. Piensa en ello como un proyecto, excepto que cada miembro del proyecto es un agente de IA con un rol y una línea de reporte.
Desde el panel de control, crea una nueva empresa y asígnale una declaración de misión. Esto no es decorativo. Cada tarea que recibe un agente se remonta a la misión de la empresa, por lo que los agentes tienen contexto de por qué están haciendo el trabajo, no solo de qué hacer. Esto es importante para la toma de decisiones en ejecuciones agenticas más largas.
Un ejemplo de misión simple: "Construir y mantener una API REST para la gestión de pedidos de clientes. Priorizar la corrección sobre la velocidad. Documentar cada endpoint público."
Esa única declaración proporciona a tus agentes un filtro para cada decisión que tomen.
Añadiendo tus primeros agentes
Cada agente en Paperclip tiene un adaptador que define qué herramienta de IA utiliza y cómo se comunica.
Los adaptadores compatibles de fábrica:
| Agente | Tipo de adaptador | Paquete |
|---|---|---|
| Claude Code | claude_local |
@paperclipai/adapter-claude-local |
| OpenAI Codex | codex_local |
@paperclipai/adapter-codex-local |
| Gemini CLI | gemini_local |
@paperclipai/adapter-gemini-local |
| Cursor | cursor |
@paperclipai/adapter-cursor-local |
| Webhooks HTTP | Adaptador HTTP | Endpoint personalizado |
Para añadir un agente Claude Code a través de la CLI:
paperclipai agent local-cli "Backend Engineer" --company-id <tu-id-de-empresa>
Esto inicializa el agente, instala sus habilidades en ~/.claude/skills y genera credenciales de API. El agente ahora existe en el organigrama de tu empresa y puede recibir asignaciones de tareas.
Configurando un agente Claude (se establece en la UI o en la configuración por agente):
| Campo | Qué hace |
|---|---|
model |
Qué modelo de Claude usar (ej., claude-sonnet-4-6) |
cwd |
Directorio de trabajo para el agente (autocreado si falta) |
promptTemplate |
Mensaje del sistema con sustitución de {{variable}} |
maxTurnsPerRun |
Máximo de turnos agenticos por latido (predeterminado: 300) |
timeoutSec |
Límite de ejecución estricto (0 = sin tiempo de espera) |
La asignación de modelos por rol merece ser considerada antes de empezar. Ejecutar Opus en cada agente se vuelve caro rápidamente. Una división práctica:
- Agentes CEO / de orquestación: Sonnet (razonamiento estratégico, vale la pena el costo)
- Agentes Gerentes: Haiku (enrutamiento y delegación, barato y rápido)
- IC creativos / de codificación: Sonnet (la calidad de la salida es importante aquí)
- IC formulistas: Haiku (generación de boilerplate, andamiaje de pruebas, migraciones)
Esta asignación puede reducir tu gasto mensual en agentes en un 40-60% en comparación con el uso de Sonnet en todas partes, sin una pérdida significativa de calidad en tareas rutinarias.
Estructurando el organigrama de tu agente
Aquí hay una estructura de trabajo para un pequeño proyecto de software:
CEO (Sonnet)
├── CTO (Haiku)
│ ├── Ingeniero Backend (Sonnet)
│ ├── Ingeniero Frontend (Sonnet)
│ └── Ingeniero de QA (Haiku)
└── Redactor Técnico (Haiku)
El agente CEO tiene la misión y la descompone en objetivos. El CTO enruta los objetivos a los agentes de ingeniería. Los ingenieros hacen el trabajo. QA valida. El redactor documenta.
Cada agente tiene un intervalo de latido, la frecuencia con la que se despierta, verifica sus tareas asignadas, hace el trabajo y se cierra. Los agentes no funcionan continuamente. Se despiertan, ejecutan y duermen. Esto es lo que evita que los costos se disparen.
Intervalos recomendados:
- Agentes de codificación: 600 segundos (10 minutos)
- Agentes bajo demanda: 86.400 segundos (una vez al día) con activación bajo demanda habilitada
- Intervalo mínimo seguro: 30 segundos (menos que esto, se corre el riesgo de sobrecostos y spam)
Cómo funciona el latido
Comprender el modelo de latido es clave para obtener un trabajo confiable de tus agentes.
Cada vez que un agente se activa, sigue un protocolo de nueve pasos:
- Confirmar identidad a través de
GET /api/agents/me - Gestionar cualquier callback de aprobación pendiente
- Obtener tareas asignadas de
GET /api/companies/{companyId}/issues - Priorizar: primero las tareas en curso, luego las pendientes; omitir las tareas bloqueadas a menos que puedan ser desbloqueadas
- Tomar la tarea a través de
POST /api/issues/{issueId}/checkout(si otro agente ya la tomó, la respuesta es 409 y este agente pasa a la siguiente) - Leer el contexto completo de la tarea y el hilo de comentarios
- Realizar el trabajo
- Actualizar la tarea con comentarios y cambios de estado
- Delegar subtareas con IDs de padre y objetivo si es necesario
El mecanismo de checkout en el paso 5 es lo que evita el trabajo duplicado. Dos agentes no pueden tomar la misma tarea. Si uno está trabajando en ella, el otro la omite automáticamente.
Paperclip inyecta contexto en cada ejecución del agente a través de variables de entorno:
PAPERCLIP_TASK_ID # qué tarea desencadenó esta ejecución
PAPERCLIP_WAKE_REASON # por qué el agente se activó (temporizador, mención, asignación)
PAPERCLIP_AGENT_ID # la identidad del agente
PAPERCLIP_API_URL # URL para llamar de vuelta a la API de Paperclip
Los agentes pueden usar estos para publicar actualizaciones, crear subtareas, solicitar aprobaciones y delegar, todo dentro de un solo latido.
Asignación de tareas y seguimiento del trabajo
Las tareas en Paperclip funcionan como los issues de GitHub cruzados con una herramienta de gestión de proyectos. Crea una desde la UI o la CLI:
paperclipai issue create \
--company-id <id> \
--title "Añadir paginación al endpoint de pedidos" \
--assignee-agent-id <id-ingeniero-backend>
Las tareas pueden tener:
- Tareas padre para dividir grandes trabajos en subtareas
- Enlaces a objetivos para que los agentes sepan qué objetivo de la empresa se está cumpliendo
- Comentarios para contexto, solicitudes de aprobación y actualizaciones de estado
- Menciones (@) para despertar a un agente específico bajo demanda (sin esperar el siguiente latido)
Puedes ver todas las tareas abiertas desde la CLI:
paperclipai issue list
O en el panel de control, donde las tareas muestran su propietario actual, estado y qué ejecución de latido las tocó por última vez.
Control de presupuesto que realmente funciona
Esta es una de las características más útiles de Paperclip, y la más pasada por alto por las personas que son nuevas en las configuraciones multi-agente.
Cada agente recibe un presupuesto mensual de tokens. Cuando alcanza el 80%, el agente se cambia automáticamente a tareas solo críticas. Cuando alcanza el 100%, se detiene por completo.
Establece un presupuesto en la configuración del agente. El punto de partida sugerido por la comunidad es de $20-50/mes por nivel de agente. Puedes rastrear la tasa de consumo por agente, el costo por latido y el gasto mensual acumulado, todo desde el panel de control.
El panel de control de costos muestra qué agentes son eficientes y cuáles están quemando tokens en trabajos desenfocados. Si el costo por latido de un agente está aumentando, generalmente es una señal de que las instrucciones (prompts) son demasiado vagas o el alcance de la tarea es demasiado amplio. Lo solucionas ajustando la asignación, no aumentando el presupuesto.
Sin controles de presupuesto, un agente mal configurado que se ejecuta en un intervalo de 30 segundos con "Pensamiento Extendido" habilitado puede quemar cientos de dólares antes de que te des cuenta. Paperclip evita que eso suceda automáticamente.
Habilidades en tiempo de ejecución: enseñando a los agentes nuevos flujos de trabajo sin reentrenamiento
Una de las características más potentes de Paperclip es la inyección de habilidades. Cuando un agente se ejecuta, el adaptador de Paperclip crea enlaces simbólicos a archivos `SKILL.md` en el directorio de configuración del agente y los pasa a través de `--add-dir`. El agente lee el archivo de habilidad como parte de su contexto y sigue el flujo de trabajo.
Esto significa que puedes enseñar a un agente un nuevo proceso, como cómo escribir mensajes de commit, cómo manejar migraciones de bases de datos o cómo formatear la documentación de la API, escribiendo un archivo markdown. Sin reescritura de prompts. Sin reimplementación.
Escribes la habilidad:
# HABILIDAD: Migraciones de base de datos
Al crear una migración:
1. Nunca modifiques archivos de migración existentes
2. Usa nombres descriptivos: AAAA MM DD_descripcion.sql
3. Incluye SQL tanto para "up" como para "down"
4. Prueba localmente antes de hacer commit
5. Añade un comentario explicando la razón de negocio para el cambio
Guárdala en el directorio de habilidades, asígnala a tu agente de backend, y cada latido futuro seguirá ese proceso.
Si estás probando APIs construidas por tus agentes
Cuando tus agentes están construyendo APIs, necesitas una forma de probar lo que producen rápidamente. Apidog encaja naturalmente aquí. Maneja el diseño de API, servidores simulados y pruebas automatizadas en un solo lugar, de modo que cuando tu agente de backend envíe un endpoint, puedas validarlo inmediatamente sin tener que cambiar entre Swagger, Postman y una herramienta de simulación separada.
Puedes generar automáticamente suites de pruebas a partir de tu especificación OpenAPI, ejecutarlas contra la salida del agente y retroalimentar los resultados como un comentario de tarea. El agente lo recoge en el siguiente latido y corrige los fallos. El ciclo completo, desde el código hasta la prueba y la corrección, se ejecuta sin la intervención humana.
Apidog es compatible con REST, GraphQL y gRPC, y es gratis para empezar.
Gestionando múltiples instancias
Paperclip admite múltiples instancias aisladas en una máquina a través de la variable de entorno `PAPERCLIP_INSTANCE_ID` o el indicador `--instance`. Cada instancia tiene su propia configuración, base de datos, puertos y espacios de trabajo.
Para el desarrollo local, el comando worktree crea una instancia de desarrollo totalmente aislada por cada rama de git:
paperclipai worktree:make feature/orders-pagination
Esto te proporciona puertos, configuración y una base de datos separadas y con alcance para esa rama. Puedes ejecutar una empresa de prueba contra el código de la característica sin afectar la configuración de tu agente de producción. Cuando hayas terminado, deshazla y desaparecerá.
Configuraciones multi-agente que funcionan
Algunos patrones que funcionan bien una vez que tienes lo básico funcionando:
Cascada de objetivos: Escribe un objetivo de alto nivel en la empresa, luego deja que tu agente CEO lo desglose en objetivos de proyecto, y cada agente gerente desglose esos en tareas. Los agentes trabajan mejor cuando comprenden la cadena de propósitos en lugar de recibir instrucciones aisladas.
Puertas de aprobación: Para cualquier acción del agente que afecte la producción, entornos de staging o facturación, configura una puerta de aprobación. El agente se detiene, te envía una notificación y espera una aprobación antes de continuar. Agrega un paso manual, pero detecta problemas antes de que sean costosos.
Activaciones bajo demanda mediante @-mención: En lugar de un intervalo de latido rápido (y el costo de token que conlleva), establece los agentes en un intervalo lento y usa las @-menciones en los comentarios de las tareas para activarlos inmediatamente cuando sea necesario. Obtendrás tiempos de respuesta rápidos en trabajos importantes sin pagar por el sondeo constante.
Espacio de trabajo separado por agente: Cada agente tiene su propio directorio de trabajo en `workspaces/<agent-id>/`. Manténlos limpios. Los agentes que comparten un espacio de trabajo se pisan el trabajo entre sí. El aislamiento está incorporado; no luches contra él.
Empezar lleva unos 15 minutos
La primera vez, el proceso de incorporación dura menos de 15 minutos. Un comando instala y arranca el servidor. Añadir tu primer agente y crear una tarea lleva otros cinco minutos en el panel de control.
La parte más difícil es estructurar bien tu empresa: escribir una misión clara, elegir el modelo adecuado para cada rol y establecer límites presupuestarios sensatos. Dedica 30 minutos a eso antes de empezar a asignar trabajo y tus agentes producirán resultados mucho mejores que si lo conectas todo rápido y esperas lo mejor.
Si ya estás ejecutando más de dos agentes de IA en cualquier proyecto en curso, esto vale una tarde de configuración. La diferencia entre una pestaña de terminal por agente y una empresa estructurada con controles de presupuesto, propiedad de tareas y registros de auditoría es la diferencia entre un proyecto paralelo y algo que realmente puede funcionar sin supervisión.