Sheila, de Soapbox: un agente contable de código abierto hecho con scripts pequeños y un AGENTS.md, sobre OpenCode y Claude

En dos frases

Soapbox, una pequeña empresa de software libre que vive de donaciones, creó un agente llamado Sheila que hoy gestiona las facturas de sus colaboradores, los pagos en dólares y en bitcoin, la contabilidad y la conciliación bancaria mensual, con el agente de código OpenCode y Claude Opus 4.6, más de 50 scripts de una sola tarea y un único archivo largo de instrucciones, AGENTS.md. Es un testimonio de primera mano sin cifras, pero todo está publicado como código abierto, así que se puede leer exactamente cómo funcionan los controles y dónde son solo instrucciones.

Quién lo hace y por qué interesa

Alex Gleason presentó Sheila en el blog de Soapbox el 6 de marzo de 2026 y ese mismo día en un «Show HN» de Hacker News. Soapbox desarrolla herramientas de código abierto para redes sociales descentralizadas, recaudación de fondos y creación de aplicaciones, y su página «About» dice que se sostiene «entirely» con subvenciones y donaciones. Sus gastos pasan por OpenCollective, de modo que pagar a un colaborador es un trabajo a dos bandas: pagarle y, después, recuperar el dinero de la colecta con la factura correcta.

El caso interesa por tres motivos:

• Es la administración real de una empresa pequeña, no una demo de un proveedor. Facturas de colaboradores, transferencias, pagos en bitcoin, resúmenes fiscales y conciliación de fin de mes son trabajo habitual en muchas pymes.
• El diseño es poco común y se puede trasladar. No hay motor de flujos ni «plataforma de agentes»: es un agente de código que lee un manual de procedimiento en lenguaje natural y llama a scripts pequeños.
• Todo es público. El repositorio (AGPL-3.0) incluye los scripts, la configuración de ejemplo y el AGENTS.md completo, y su historial enseña cómo cambió el procedimiento después del lanzamiento.

Dos advertencias de entrada: Soapbox no da números, y desarrolla herramientas propias de creación de apps con IA, así que tiene cierto interés en el mensaje de «constrúyete tu agente», aunque no vende ni Sheila ni OpenCode.

Qué hace Sheila

Según la entrada y el README, Sheila cubre todo el ciclo de pago a colaboradores:

1. Lee las facturas del email por IMAP, con el hilo completo cuando va a actuar.
2. Las registra antes que nada: una carpeta numerada en Google Drive con el PDF y una fila en la pestaña del mes de la hoja de seguimiento de pagos, con estado PENDING, más una anotación en una pestaña de registro aparte.
3. Acusa recibo al remitente (un paso obligatorio en las instrucciones).
4. Paga por ACH o transferencia con la API del banco Mercury, o en bitcoin con Kraken, con una cartera Lightning o con un intercambio de Lightning a la cadena principal.
5. Pide el reembolso: genera la factura propia de Soapbox y presenta el gasto en OpenCollective, y lo sigue hasta que se aprueba y se paga.
6. Cierra la fila como COMPLETE y escribe al colaborador con datos que puede comprobar.

Además lleva un libro de finanzas aparte con ingresos, gastos, cuenta de resultados y resumen de pagos a colaboradores para el formulario 1099 de Estados Unidos y, desde finales de marzo de 2026, una conciliación mensual de los movimientos de Mercury con la hoja. Gleason cuenta que abre una terminal, pregunta «what’s the status?» y Sheila le dice qué está hecho, qué está pendiente y qué está bloqueado.

Herramientas y arquitectura

El README dibuja la arquitectura como un agente que llama a una lista de comandos npm run. En la práctica hay tres capas:

• El agente: OpenCode, un agente de código abierto (licencia MIT) que funciona en la terminal y lee automáticamente el archivo AGENTS.md de la carpeta del proyecto. Soapbox dice que Sheila se desarrolló y probó con Claude Opus 4.6 y avisa de que otros modelos pueden saltarse pasos, inventarse identificadores de transacción o pagar a quien no toca.
• El procedimiento: AGENTS.md, unas 600 líneas al lanzarlo y unas 960 cuando lo leímos. Define las columnas de la hoja y los estados, las tres vías de pago, cómo escribir a los colaboradores, la política de direcciones de bitcoin, la revisión de estado y los pasos de la conciliación.
• Las herramientas: 56 scripts en TypeScript, cada uno con una sola tarea (consultar un saldo, listar movimientos del banco, enviar un pago, añadir una fila, subir un archivo, presentar un gasto). Todos admiten --json y --dry-run. La configuración y las credenciales están en un sheila.yaml que no se sube al repositorio. No hay base de datos: todo el estado vive en Google Sheets, el email y Google Drive.

La lección principal de Gleason está en esa división. Su primera versión intentaba programar flujos complejos de varios pasos y resultó «frágil e inflexible»; la segunda usó scripts granulares, probados uno a uno, y flujos escritos en lenguaje natural que el agente encadena. Defiende que un agente de código con una persona al lado funciona mejor que las plataformas de agentes autónomos, porque la fiabilidad sale de cientos de ciclos de probar, encontrar un caso raro y corregir un script o una instrucción.

Los controles escritos en el procedimiento

Leyendo AGENTS.md y el código, estas son las salvaguardas:

• Lista de remitentes autorizados. Los scripts de email marcan con un aviso «PHISHING RISK» a cualquier remitente que no sea colaborador o administrador, y las instrucciones lo tratan como parada obligatoria para todo lo relacionado con pagos; el nombre visible nunca vale como identidad.
• Registrar antes de pagar, para que una sesión interrumpida deje rastro.
• Solo destinatarios guardados. Los pagos bancarios van a destinatarios que ya existen en Mercury; los colaboradores que cobran en bitcoin deben usar una única dirección fija ya guardada en Kraken, y una dirección nueva necesita a una persona.
• Límites. La configuración tiene un máximo global por factura y límites opcionales por colaborador, por factura y por mes.
• Aprobación en el banco para las transferencias internacionales, que pasan por una vía de Mercury que exige aprobarlas en su panel.
• Confirmación humana en la conciliación. El agente presenta los cargos sin explicar agrupados por tipo y no puede seguir hasta que el usuario confirma cuáles se reclaman.
• Una persona en la terminal. En palabras de Gleason, Sheila puede redactar un email o preparar un pago, pero él ve lo que hace antes de que salga.

Un matiz de nuestra lectura del código: los límites y la lista de remitentes aparecen como avisos en los scripts de email y se aplican mediante las instrucciones; no encontramos en el script de pagos de Mercury una comprobación que rechace un importe por encima del límite. Con una persona vigilando es aceptable, pero es lo primero que habría que reforzar si se quiere que el agente trabaje sin supervisión.

Cómo replicarlo paso a paso

1. Elige un circuito y dibújalo. De la factura del proveedor al pago y a la reclamación o el asiento. Apunta los estados (recibida, registrada, pagada, reclamada, cerrada) y las columnas que necesitas.
2. Comprueba qué sistemas tienen una API utilizable. Sheila funciona porque Mercury, Kraken, Google y OpenCollective la tienen; el README recuerda que la mayoría de los bancos no ofrecen nada parecido. Si tu banco no la tiene, quédate en un fichero de pagos que suba una persona (en España, por ejemplo, una remesa de transferencias SEPA que se firma en la banca electrónica).
3. Escribe un script por acción, con modo de prueba y salida JSON, y prueba cada uno por separado con importes mínimos o en un entorno de pruebas.
4. Redacta el procedimiento en AGENTS.md: orden de los pasos, paradas obligatorias, redacción de los emails, qué registrar y cuándo parar y preguntar.
5. Pon los límites en el código, no solo en el texto. Haz que el script de pago rechace destinatarios desconocidos e importes por encima del límite, diga lo que diga el agente.
6. Configura los permisos del agente. En OpenCode cada patrón de comando puede ser allow, ask o deny; por ejemplo, permite los scripts de solo lectura y pon en ask todos los de pago (es una sugerencia nuestra; el repositorio de Sheila no trae ese archivo).
7. Úsalo con supervisión durante semanas, corrige scripts e instrucciones después de cada sorpresa y solo entonces plantéate reducir la vigilancia.
8. Añade una conciliación mensual de los movimientos del banco contra tu registro, en la que el agente propone y una persona confirma.

Un ejemplo práctico (ilustrativo)

Imagina que un colaborador habitual envía el 3 de noviembre una factura de 4.800 $. Escribes «process invoices». El agente lee el hilo, ve que el remitente está en la lista y que el importe no llega al límite de 10.000 $ por factura, crea la carpeta en Drive, sube el PDF, añade una fila PENDING, lo anota en el registro y responde para confirmar la recepción. Después ejecuta el script de pago de Mercury con --dry-run, te enseña el destinatario guardado, el importe y el saldo y, cuando apruebas la ejecución real, envía el ACH, pasa la fila a PAID, escribe al colaborador y prepara la reclamación en OpenCollective con la factura propia de Soapbox. Si el mismo email hubiera llegado desde una dirección desconocida, o con datos bancarios o de bitcoin nuevos, se pararía y te avisaría. Los importes y la fecha son nuestros, no de Soapbox.

Resultados declarados por la fuente

Soapbox solo declara resultados cualitativos: Sheila sustituyó todo su circuito contable y ahorra mucho tiempo aunque esté supervisada. No hay cifras de facturas al mes, horas ahorradas, coste del uso del modelo ni errores evitados. Lo que sí se puede comprobar es la actividad: el repositorio público tiene commits de marzo a agosto de 2026, entre ellos un flujo de conciliación mensual, arreglos para emails que se escapaban o se emparejaban mal y una corrección para las transferencias internacionales, lo que apunta a un uso real continuado. Por eso el nivel de evidencia es experiencia, no un resultado medido.

Limitaciones y riesgos

• Mueve dinero de verdad. El propio README avisa de que puede enviar pagos ACH, transferencias, bitcoin y Lightning y de que el usuario responde de cada operación.
• Dependencia del modelo. Solo se probó Claude Opus 4.6; según los autores, otros modelos podrían inventarse identificadores o pagar a la persona equivocada.
• Las instrucciones no son controles. Varias salvaguardas dependen de que el agente siga AGENTS.md; por eso importa la persona en la terminal.
• Phishing e inyección de instrucciones. El email es una entrada no fiable que el agente lee; la lista de remitentes ayuda, pero un buzón de colaborador comprometido la pasaría.
• Una hoja de cálculo como libro. Sirve para una empresa pequeña, pero no hay contabilidad por partida doble, cierre de periodos ni separación de funciones; el conector con ERPNext es opcional y no forma parte del flujo descrito.
• Muy ligado a su contexto. OpenCollective, los pagos en bitcoin y los 1099 de Estados Unidos son propios de Soapbox. En España habría que encajar además la factura electrónica, VERI*FACTU o el SII, y los modelos de retenciones (como el 111) si los colaboradores son profesionales.
• Credenciales. Un solo archivo guarda las claves del banco, el exchange, el email y Google; protégelo y usa los permisos de API más restringidos posibles.

Errores comunes

• Construir un gran script o flujo que «lo hace todo» en lugar de pasos pequeños y comprobables (la versión 1 de Soapbox).
• Dejar que el agente pague primero y registre después.
• Fiarse del nombre visible o de una cuenta bancaria nueva que llega por email.
• Escribir los límites solo en el prompt, sin comprobarlos en el código de pago.
• Dejarlo trabajar solo antes de muchos ciclos supervisados.
• Saltarse la conciliación mensual, que es la que detecta lo que el circuito no vio.

Conclusiones

Sheila es un buen ejemplo de lo que ya puede hacer un equipo financiero pequeño: no una plataforma, sino un agente de código con un procedimiento escrito y claro y un conjunto de scripts aburridos, de una sola tarea, contra sistemas que tienen API. El valor del caso no está tanto en el ahorro de tiempo declarado, que no se cuantifica, como en el diseño publicado: registrar antes de pagar, pagar solo a destinatarios guardados, parar ante remitentes desconocidos, confirmación humana en la conciliación y una persona vigilando. Si lo copias, conserva esa estructura y pasa los límites críticos de las instrucciones al código.