Las finanzas de pareja en Markdown: Thiago Diniz deja que Claude transcriba los recibos y que la CLI spltty haga las cuentas

En dos frases

Thiago Diniz, desarrollador brasileño, lleva el dinero que comparte con su mujer en una carpeta de tablas Markdown: Claude lee lo que llega desordenado (extractos de tarjeta, capturas, fotos de recibos de Pix, un «he pagado 700 reales de la prueba del vestido») y spltty, una pequeña CLI en Ruby que construyó con Claude, escribe cada fila y calcula quién debe a quién. Es un caso de primera mano bien documentado, con su propia comparativa de costes, y todo lo necesario para copiarlo, incluidas las instrucciones del agente y la skill, está publicado con licencia MIT.

Quién lo hace y por qué importa

La mayoría de las parejas comparten el dinero con lo que Diniz llama una «documentación muy pobre». Hay gastos de él, gastos de ella y gastos comunes que no se reparten a medias. En su caso coincidieron a la vez una boda, la reforma de un piso y un viaje de seis semanas a Montreal, y los justificantes llegaban de todas las formas posibles: extractos en PDF, capturas del recibo de la tarjeta, fotos de recibos de Pix (el sistema de pagos inmediatos de Brasil) y notas habladas.

Había probado aplicaciones para dividir gastos, normalmente una distinta para cada viaje, y después hojas de cálculo. Las dos fracasaron por lo mismo, explica: lo difícil no es la aritmética, sino transcribir cuarenta líneas de un extracto y decidir a quién corresponde cada una. Es justo el tipo de trabajo difuso y repetitivo que un modelo de lenguaje hace bien, y el que acaba con la mayoría de los presupuestos domésticos.

La fuente es su propio artículo del 2 de agosto de 2026, «Building a personal finance tracker with Claude», que recorre cuatro versiones en diez semanas. Publicó el código esa misma semana como gema con licencia MIT y lo presentó en Show HN el 5 de agosto (8 puntos y un único comentario de un lector, «Very cool!», cuando lo consultamos, así que apenas hay debate de la comunidad que valorar). No tiene ningún producto comercial alrededor de spltty. Contrastamos el artículo con el repositorio, sus plantillas y el paquete en RubyGems, y probamos la herramienta nosotros mismos.

Cómo evolucionó el sistema

Lo interesante no es la herramienta final, sino cómo cada fallo trasladó una responsabilidad del modelo al código.

Versión 1: un archivo de instrucciones y una tabla. Inspirado por ledger-cli, creó una carpeta de archivos Markdown y un CLAUDE.md que explicaba cómo rellenarlos. La primera tabla tenía cinco columnas: fecha, concepto, importe en reales, responsable y origen. Le pasó una captura del recibo de una tarjeta y Claude extrajo 38 filas, confirmando cada una con él antes de escribirla.

Versión 2: el dinero real rompió el esquema. «Responsable» hacía dos trabajos: una fila con el nombre de su mujer, ¿significaba que ella había pagado o que ella debía? Para liquidar hacen falta los dos datos, así que la columna se dividió en Paid By (quién adelantó el dinero) y Responsible (a quién se imputa el gasto). Tampoco bastaba un solo libro: la reforma, la boda, la vivienda en alquiler y el viaje pasaron a tener cada uno su libro y sus reglas de reparto. Y el viaje obligó a llevar varias divisas: importes en dólares canadienses y estadounidenses guardados en reales sin perder el importe original, porque el tipo de cambio que aplica una tarjeta brasileña puede no coincidir con el del día de la compra.

Versión 3: hablar ya no bastaba. Con unos cientos de filas, la pregunta obvia era quién debe a quién. Claude podía sumarlo, pero él tendría que comprobarlo cada semana. Así que, con ayuda de Claude, escribió scripts/totals.py, que leía cualquier libro a partir de su fila de cabecera, aplicaba los repartos e imprimía los totales por persona.

Versión 4: la CLI. El 5 de julio sustituyó el script por spltty, en Ruby. Quedaba un problema: las filas las seguía escribiendo Claude editando Markdown, y las filas escritas a mano se desvían: fechas incoherentes, columnas descuadradas y tokens gastados en teclear datos. Ahora add escribe la fila, groups convierte «Both» de palabra mágica en un reparto con nombre (50/50 en general, 65/35 en el libro de la boda), totals y settle se encargan de las cuentas, y la rutina de importación se convirtió en una skill /ingest para no tener que explicarla en cada sesión. El CLAUDE.md generado dice sin rodeos que el agente nunca debe editar a mano una tabla ni sumar por su cuenta.

Herramientas y arquitectura

El espacio de trabajo que crea spltty install tiene cinco piezas:

• accounts/: un libro por cuenta. Los libros mensuales son una carpeta con un archivo YYYY-MM.md por mes; los de un solo archivo (NOMBRE.ledger.md) encajan con proyectos con principio y fin, como un viaje.
• Un archivo de notas por libro cuya cabecera YAML guarda el responsable por defecto y los grupos de reparto de ese libro, sincronizada en los dos sentidos con .spltty/config.json.
• sources/INDEX.md: el registro de cada archivo original que se deja en sources/, con su estado (pendiente, procesado o sustituido) y los conceptos extraídos.
• CLAUDE.md: se genera con tus respuestas (participantes, libros, grupos, tarjetas) y describe el formato de la tabla, las reglas para asignar cada gasto y la CLI.
• .claude/skills/ingest/SKILL.md: el procedimiento que sigue el agente cuando sueltas un archivo o pegas texto con gastos.

El reparto de papeles es estricto. El modelo lee, hace OCR, transcribe, interpreta nombres de comercios («MOMENTOS BUFFET E RECE es probablemente el catering de la boda») y pregunta lo que no puede deducir, agrupando las preguntas. Guarda su interpretación en un INGEST-WIP.md excluido de Git para que el trabajo sobreviva a una sesión interrumpida. La CLI escribe las filas, rellena los datos por defecto de cada tarjeta, rechaza como errata un nombre de libro desconocido, aplica los repartos y registra las liquidaciones como filas normales (Paid By = deudor, Responsible = acreedor), de modo que cada pago compensa la deuda en todos los cálculos posteriores. Git aporta un historial comparable de cada cambio.

Paso a paso para replicarlo

1. Instala Ruby y spltty. Ruby 3.1 o posterior; macOS trae un Ruby más antiguo, así que allí conviene Homebrew. En Linux sirven la gema o el script de instalación.
2. Decide los libros antes de importar nada. Un libro mensual para el gasto diario de casa y un libro de un solo archivo por proyecto (reforma, boda, viaje) es la forma a la que llegó el autor.
3. Crea el espacio de trabajo con spltty install, indicando los participantes, el grupo común y su reparto, y los libros. Acepta el git init.
4. Da de alta cada tarjeta con spltty methods add: quién la paga normalmente, a quién se imputa por defecto y el día de cargo del recibo. Las filas de tarjeta llevan entonces la fecha de cargo, así que todas las de un mismo extracto comparten fecha.
5. Cambia el reparto en los libros que lo necesiten con spltty groups add NOMBRE -s A:65,B:35 -l LIBRO.
6. Abre la carpeta en Claude Code y suelta un extracto o un ticket. El agente escribe INGEST-WIP.md, pregunta una sola vez lo que no puede deducir, ejecuta spltty add … -y por cada fila confirmada y actualiza sources/INDEX.md.
7. Revisa y haz commit. Lee el diff del libro, ejecuta spltty totals y confirma los cambios.
8. Liquida cuando os paguéis con spltty settle LIBRO, o con spltty settle para todos los libros que no sean de referencia.

Cópialo y adáptalo

Los bloques 1 a 3 proceden de spltty, de Thiago Diniz, © 2026, licencia MIT, en el commit 379fb8c, y se reproducen tal cual, en inglés. El bloque 4 es nuestra propia prueba y el bloque 5, una plantilla de Agents Finance.

Requisitos previos: Ruby 3.1 o posterior (o Homebrew), Git y Claude Code con un plan de pago de Claude (u otro agente que lea CLAUDE.md). No hace falta conectar el banco ni ninguna clave de API: las entradas son archivos que sueltas en la carpeta.

1. Instalar y crear el espacio de trabajo

Del README. Los comentarios dicen: elige un método de instalación; configuración interactiva en una carpeta vacía; o sin preguntas.

# Pick one installation method
brew tap thiagodiniz/spltty https://github.com/thiagodiniz/spltty
brew install spltty
# or (Ruby >= 3.1)
gem install spltty

# Interactive set-up in an empty folder
mkdir ~/finances && cd ~/finances
spltty install

# Or non-interactively
spltty install ~/finances -y -P Ana,Bruno -s Ana:60,Bruno:40 -l HOME,TRIP --no-git

2. La skill /ingest (literal)

spltty install la escribe en .claude/skills/ingest/SKILL.md. Fuente: templates/skills/ingest/SKILL.md. En resumen: el agente lee el archivo, guarda su interpretación en INGEST-WIP.md, archiva el original en sources/, resuelve libro, pagador y responsable (o pregunta), añade cada gasto con spltty add y anota la metodología del lote en sources/INDEX.md; nunca adivina, nunca edita la tabla a mano y nunca inventa importes.

---
name: ingest
description: Ingest a raw source file (PDF, image/screenshot, txt, audio transcript) or pasted expense text into the ledger — read/OCR/interpret it, organize the expenses, and add them with the spltty CLI. Use whenever raw expense inputs are dropped into the prompt for this expense tracker.
---

# Ingest raw inputs into the ledger

Turn a raw input — a source file (PDF, image/screenshot, `.txt`, audio transcript) or expense text
pasted straight into the prompt — into ledger rows. This is the ingestion path of the workflow in
`CLAUDE.md`; that file is the source of truth for the table schema, payment-method defaults, split
groups and routing. Read it if you need those details.

## When to use

A source file or raw expense text was sent to the prompt. Treat its arrival as "ingest this" — do not
ask what to do with it. If instead the ask was for totals or a settlement, that's `spltty totals` /
`spltty settle`, not this skill.

## Do

1. **Read & interpret the input yourself.** OCR images/screenshots, read PDFs (some are
   password-protected — the password is usually given), transcribe audio. Extract each expense:
   title, value (two decimals), and date if present. Never invent a value from blurry or uncertain
   content — ask about that line.
2. **Checkpoint the inferred work.** As soon as you've interpreted the input, write the structured
   expenses to **`INGEST-WIP.md`** at the workspace root — one row per expense with the extracted
   fields plus the resolved (or still-open) ledger / paid-by / responsible and any open questions.
   This preserves work across interruptions and allows review before it lands. It's gitignored.
   Delete it once every row has been added with `spltty add`.
3. **Save file inputs.** If the input is a file (not chat text), make sure it lives under `sources/`
   and gets a `sources/INDEX.md` row (`pending` now, `processed` at the end).
4. **Resolve the three routing fields** for each expense — **ledger**, **paid-by**, **responsible**:
   - If the prompt states them, use them.
   - Else if the **payment method** matches a configured card, pre-fill paid-by / responsible / date
     from it (`spltty methods` lists them).
   - Else **ask** — one batched confirm for all pending expenses. Never guess these three.
5. **Read for context only when needed.** Reading a ledger's entries/notes is fine to match a prior
   categorization, dedup against an existing bill, or copy a split convention — but only when the
   task genuinely requires it. Don't read files speculatively.
6. **Add each expense with `spltty add`** — never hand-edit a ledger table:

   ```sh
   spltty add "<title>" -l <LEDGER> -v <value> -p <paid-by> -m "<method>" -r <responsible> -y
   ```

   - Card entries can omit `-p`/`-r`/`-d` (defaulted from the card).
   - Multi-currency ledgers take `-o <orig-value> -c <CUR>`.
   - Set `-s <source-filename>` when the row came from a file in `sources/`.
   - If it fails with *unknown ledger*, that is a typo guard, not a missing feature: use one of
     the ledgers it lists. Only pass `--create-ledger` after confirming a new account is wanted.
7. **Record per-batch methodology** (FX rates, exclusions, dedup, subtotals) in `sources/INDEX.md` —
   not in the `*.notes.md` files, which hold only forward-applicable rules. Update the source's row
   to `processed` with the extracted titles and the ledger(s) they landed in.

## Prefer the CLI

If the operation has a `spltty` command (`add`, `totals`, `settle`, `list`, `sync`, `groups`,
`methods`), use it rather than doing the work by hand — unless explicitly told otherwise.

## Never

- Never guess ledger, paid-by, or responsible — confirm when not inferable.
- Never conflate **Paid By** (who fronted the money) with **Responsible** (who bears the cost).
- Never hand-edit a ledger table to record spend, or tally totals by hand.
- Never invent values from uncertain source content.
- Never misspell a participant's name — they are matched literally.

3. Las reglas del CLAUDE.md generado (extracto)

spltty install genera el CLAUDE.md a partir de templates/CLAUDE.md.erb con tus participantes, libros, grupos y tarjetas. Estas son sus dos últimas secciones tal como salieron en nuestro espacio de prueba (libro por defecto CASA): los siete pasos del flujo (recibir, extraer, asignar libro, confirmar, añadir con la CLI, actualizar el registro y calcular) y la lista de cosas que el agente no debe hacer nunca.

### Steps

1. **Receive** an expense (text, audio, image, PDF).
2. **Parse** title + value (+ date). For files, save the raw input under `sources/` and add a row to
   `sources/INDEX.md`.
3. **Route** to a ledger — confirm which one when it isn't obvious. Default: `CASA`.
4. **Confirm** before writing: (a) who paid + payment method, (b) responsibility — a group name or a
   person. A configured card pre-fills both.
5. **Add** each confirmed expense with `spltty add … -y`. Do not hand-edit the table. Per-batch
   methodology (FX, exclusions, dedup) goes in `sources/INDEX.md`.
6. **Update** `sources/INDEX.md` to mark the source processed, listing the titles extracted and the
   ledger they landed in.
7. **Compile** on demand with `spltty totals` (`--combined` to merge ledgers).

## Things to never do

- Never hand-edit a ledger table to record spend — add every expense with `spltty add`. Never
  compute totals or a settlement by hand — use `spltty totals`. Never record a settlement payment
  with `spltty add` or a hand edit — use `spltty settle`.
- Never guess which ledger an expense belongs to — confirm when it isn't obvious.
- Never guess who is responsible — always confirm.
- Never conflate **Paid By** (who fronted the money) with **Responsible** (who bears the cost).
- Never invent expense values from blurry or uncertain source content — ask for clarification.
- Never misspell a participant's name — they are matched literally.

4. Nuestra prueba con datos ficticios

Comandos del README que ejecutamos el 22 de octubre de 2026 con spltty 0.1.1 (personas ficticias, Ana y Bruno). La salida está recortada a las líneas relevantes. El comentario de «Restaurante» indica que la fila tomó como fecha el 31 de octubre, día de cargo de la tarjeta; el de groups add, que ese libro reparte 65/35; el de settle, la fila de liquidación que escribe, y el de totals CASA, que después ya no hay deuda. La última orden muestra el rechazo de un libro mal escrito.

spltty install demo -y -P Ana,Bruno -s Ana:50,Bruno:50 -l CASA --no-git
cd demo
spltty methods add "Visa 1234" -s visa-1234 -p Ana -r Both -b last
spltty add "Supermercado" -l CASA -v 84.20 -p Bruno -m cash -r Both -d 2026-10-03 -y
spltty add "Farmacia" -l CASA -v 30.00 -p Ana -m Pix -r Bruno -d 2026-10-05 -y
spltty add "Restaurante" -l CASA -v 120.00 -m visa-1234 -y   # dated 2026-10-31, the bill day
spltty groups add Both -s Ana:65,Bruno:35 -l CASA            # this ledger splits 65/35
spltty totals
# == CASA ==
# Rows: 3   Grand total: R$ 234.20
# Person              Paid          Owes           Net
# Ana               150.00        132.73        +17.27
# Bruno              84.20        101.47        -17.27
# Settlement:
#   Ana is owed — Bruno owes Ana: R$ 17.27
spltty settle CASA -y        # writes "Settlement — Bruno → Ana | 17.27 | Bruno | Pix | Ana | settle"
spltty totals CASA           # Settlement: already even.
spltty add "Cafe" -l CAS -v 5 -p Ana -m cash -r Both -y
# spltty add: unknown ledger "CAS" (known ledgers: CASA) — pass --create-ledger to create it

La comprobación a mano: el gasto común de 204,20 repartido 65/35 da 132,73 para Ana y 71,47 para Bruno, más los 30,00 de farmacia que corren enteros a cargo de Bruno, así que Bruno debe 101,47 frente a 84,20 pagados.

5. Plantilla de Agents Finance: permisos de Claude Code para el espacio de trabajo

Plantilla de Agents Finance basada en las reglas del CLAUDE.md de spltty, no un archivo publicado por el autor. Guárdala como .claude/settings.json en el espacio de trabajo para que el agente pueda ejecutar spltty y leer la carpeta, pero no escribir directamente en los libros ni en la configuración, y para que pida permiso antes de liquidar, cambiar repartos o tarjetas y hacer commit. No la hemos probado en Claude Code: comprueba la sintaxis de las reglas en la documentación vigente de permisos de Claude Code antes de fiarte de ella.

{
  "permissions": {
    "allow": [
      "Bash(spltty add:*)",
      "Bash(spltty list)",
      "Bash(spltty totals:*)",
      "Bash(spltty methods)",
      "Bash(spltty groups)",
      "Bash(git diff:*)",
      "Bash(git status)"
    ],
    "ask": [
      "Bash(spltty settle:*)",
      "Bash(spltty groups add:*)",
      "Bash(spltty methods add:*)",
      "Bash(git commit:*)"
    ],
    "deny": [
      "Edit(./accounts/**)",
      "Write(./accounts/**)",
      "Edit(./.spltty/**)",
      "Write(./.spltty/**)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ]
  }
}

Y un primer mensaje para un extracto mensual (plantilla de Agents Finance):

/ingest sources/2026-10-visa-1234.pdf
Es el recibo de octubre de la "Visa 1234". Pon todas las filas en CASA salvo
las del viaje, que van a VIAJE. No añadas ninguna fila hasta que confirme el
lote en INGEST-WIP.md. Al terminar, ejecuta `spltty totals --combined` y
enséñame el git diff de los libros.

Resultados declarados por la fuente

Todas las cifras son de Diniz y no las hemos auditado. A las diez semanas, sus libros tenían 457 filas en tres libros, resueltas en una única liquidación conjunta. Hizo la misma pregunta por las dos vías con el mismo modelo y en la misma máquina. La vía de la CLI envió unos 200 tokens de entrada (un resumen de 738 caracteres que imprime spltty totals --combined) y generó 310 de salida en 8 segundos, por 0,18 dólares. La vía de solo el modelo envió los 67.709 tokens de las tablas y generó entre 22.571 y 25.563 de salida en unos 3 minutos y 20 segundos, por entre 0,63 y 1,00 dólares en tres pasadas. Las tres dieron el mismo resultado que la CLI al céntimo: 17.930,52 reales.

Lo útil es su conclusión: no es una historia de un modelo que falla sumando, sino de pagar 25 veces más tiempo por una cifra que hay que seguir comprobando cada semana. También habla de 86 tests en la CLI, que es lo que permite seguir dejando que una IA la modifique; el repositorio que probamos tiene 115, todos en verde.

Limitaciones y riesgos

• Un hogar, un autor. La comparativa es una sola pregunta sobre sus propios datos, y el artículo no dice qué modelo de Claude usó.
• La etiqueta de la moneda es fija. En la versión 0.1.1, la columna de importe y los informes dicen R$. Los importes son números sin más, así que sirve para euros o dólares, pero todas las tablas e informes seguirán poniendo «R$».
• Los extractos son datos sensibles. El agente lee extractos y tickets completos. Guarda el espacio de trabajo en un repositorio privado o en ninguno, y ten presente que esos archivos se envían al proveedor del modelo.
• Un proyecto joven. Nueve commits, una versión (0.1.1, del 5 de agosto de 2026) y ninguna actividad posterior cuando lo revisamos. Es pequeño y se lee fácil, pero lo adoptas tú; no compras soporte.
• Las reglas dependen de que el agente las cumpla. El CLAUDE.md prohíbe editar las tablas; solo los permisos (nuestro bloque 5) o la revisión del diff lo convierten en garantía.
• La fecha de cargo oculta la de la operación. Por diseño, las filas de tarjeta llevan la fecha del recibo, lo que es correcto para liquidar y no lo es si luego quieres el gasto mensual por fecha de compra; deja la fecha en el concepto cuando importe.

Errores comunes

• Usar una sola columna de «responsable» para quién pagó y quién debe. La segunda versión de Diniz nace de ese error.
• Sumar al total conjunto un libro de proyecto que duplica filas de casa. Márcalo como libro de referencia para que totals --combined y settle lo excluyan.
• Dejar que el modelo «lo sume solo esta vez». Todo el diseño se basa en que los totales salgan siempre de la CLI.
• Registrar una devolución entre vosotros con spltty add en lugar de spltty settle, con lo que pagador y responsable quedan al revés.
• Crear un libro sin querer por una errata; con -y, spltty lo rechaza, así que no añadas --create-ledger por costumbre.

Conclusiones

Las diez semanas de Diniz son una lección compacta sobre dónde poner la IA en las finanzas de casa. El modelo es muy bueno en la parte que hace abandonar los presupuestos: leer un ticket borroso, reconocer un comercio críptico, convertir cuarenta líneas de un extracto en filas y hacer la pregunta adecuada una sola vez. No es el sitio para lo que tiene que ser exacto, repetible y barato, y su propia prueba demuestra que, incluso cuando acierta la suma, pagas más por una respuesta en la que no puedes confiar sin comprobarla. Markdown en Git, una CLI diminuta que se encarga de las cuentas y un CLAUDE.md con su skill que lo dicen por escrito: todo tiene licencia MIT y puede estar funcionando en un portátil en una tarde.