picoclaw-finance

Complete personal financial management for PicoClaw via Telegram. Track every expense, monitor budgets, set savings goals, and import bank statement PDFs — all through natural conversation.

Storage

All data is stored as JSON in finance/ inside the agent workspace:

workspace/finance/
├── transactions.json
├── budgets.json
├── goals.json
└── config.json

Data Schemas

transactions.json

{
  "transactions": [
    {
      "id": "20260511-001",
      "date": "2026-05-11",
      "type": "expense",
      "amount": 35.00,
      "currency": "BRL",
      "category": "transporte",
      "description": "Uber ate o escritorio",
      "source": "manual"
    }
  ]
}

budgets.json

{
  "budgets": [
    {
      "month": "2026-05",
      "categories": {
        "alimentacao": 800,
        "transporte": 300,
        "moradia": 1200,
        "saude": 200,
        "lazer": 400,
        "educacao": 300,
        "assinaturas": 150,
        "mercado": 600,
        "roupas": 200,
        "outros": 300
      },
      "total": 4450
    }
  ]
}

goals.json

{
  "goals": [
    {
      "id": "viagem",
      "name": "Viagem para Europa",
      "target": 8000,
      "saved": 3200,
      "created": "2026-01-10",
      "deadline": "2026-12-01"
    }
  ]
}

config.json

{
  "default_currency": "BRL",
  "categories": [
    "alimentacao", "transporte", "moradia", "saude",
    "lazer", "educacao", "assinaturas", "mercado",
    "roupas", "outros"
  ],
  "currency_symbol": "R$",
  "recurring": [
    {
      "id": "netflix",
      "description": "Netflix",
      "amount": 59.90,
      "category": "assinaturas",
      "day": 10,
      "active": true
    }
  ]
}

Commands

The agent recognizes these intents from natural language and executes them using read_file, write_file, and exec tools.

Add Expense

When user says things like:

• "gastei 35 reais em uber"
• "comprei pizza por 45 reais"
• "gastei 150 no mercado"
• "150 reais de gasolina"

Agent should:

1. Extract amount and description from message
2. Infer category from description (use map below)
3. Save to transactions.json via write_file
4. Format reply with Telegram template

Category inference:

• alimentacao → restaurante, pizza, lanche, almoco, cafe, ifood
• transporte → uber, taxi, gasolina, onibus, metro, estacionamento
• moradia → aluguel, condominio, agua, luz, internet
• saude → farmacia, remedio, medico, dentista, plano
• lazer → cinema, show, festa, jogo, bar, cerveja
• educacao → curso, faculdade, livro, udemy
• assinaturas → netflix, spotify, streaming, mensalidade
• mercado → supermercado, mercado, acougue, feira
• roupas → roupa, sapato, camisa, tenis
• outros → anything else

Add Income

When user says things like:

• "recebi 5000 de salario"
• "entrou 2000 de freela"
• "recebi 150 de dividendos"

Agent should:

1. Extract amount and description
2. Save as type "income" with category "salario", "freela", "investimentos", or "outros"
3. Confirm with Telegram template

Add Recurring Expense

When user says things like:

• "adicionar netflix 59,90 todo mes"
• "assinatura spotify 21,90 por mes"
• "adicionar conta de agua 80 todo mes"

Agent should:

1. Extract description, amount, day
2. Save to config.json under recurring array
3. On 1st of each month (via heartbeat), process all active recurring items as transactions

Monthly Summary

When user asks:

• "qual meu saldo?"
• "resumo do mes"
• "como estao minhas financas?"

Agent should:

1. Read transactions.json
2. Filter current month
3. Calculate totals per category
4. Apply formatting template

Category Breakdown

When user asks:

• "quanto gastei em alimentacao?"
• "gastos por categoria"
• "onde estou gastando mais?"

Agent should:

1. Read and filter transactions
2. Group by category
3. Sort by amount descending
4. Format with progress bars

Goals

When user says:

• "quero juntar 5000 pra viagem em dezembro"
• "adicionei 500 na meta do notebook"
• "quais minhas metas?"

Agent should:

1. Create, update, or list goals in goals.json
2. Show progress bars

Set Budget

When user says:

• "definir orcamento de 3000"
• "meu orcamento esse mes e 4000"
• "mudar orcamento para 3500"

Agent should:

1. Save total budget for current month
2. If user specifies per-category, save those too
3. Alert when spending exceeds budget

Import PDF

When user sends a PDF file or says:

• "ler esse extrato"
• "importar esse pdf"
• "extrair desse extrato bancario"

Agent should:

1. Save attached PDF to finance/imports/ via write_file
2. Run: pdftotext finance/imports/extrato.pdf - via exec
3. Parse the output text to identify each transaction
4. Present preview to user with formatted template
5. On confirmation, save all transactions
6. On rejection, discard

Telegram Formatting Templates

Transaction Confirmation

💰 *Picoclaw Finance* — Transacao Registrada
────────────────────────
🔴 *Despesa*   R$ 35,00
📂 Categoria   Transporte
📝 Descricao   Uber ate o escritorio
📅 Data        11/05/2026
────────────────────────
📊 *Resumo do Mes*
  Receitas    R$ 5.000,00
  Despesas    R$ 1.230,00
  Saldo       R$ 3.770,00
  Orcamento   41% utilizado

Monthly Summary

💰 *Resumo Financeiro — Maio/2026*
────────────────────────
📌 *Receitas*     R$ 5.000,00
💳 *Despesas*     R$ 1.230,00
📊 *Saldo*       +R$ 3.770,00
────────────────────────
📂 *Por Categoria:*
  🍔 Alimentacao    R$ 480,00  ████████░░  60%
  🚌 Transporte     R$ 320,00  █████░░░░░ 106%
  🏠 Moradia        R$ 0,00    ░░░░░░░░░░   0%
  🎮 Lazer          R$ 150,00  ██░░░░░░░░  38%
────────────────────────
💡 *Metas:*
  🎯 Viagem     R$ 3.200 / R$ 5.000  ██████░░░░  64%

Category Breakdown

📂 *Gastos por Categoria — Maio/2026*
────────────────────────
  1. 🍔 Alimentacao     R$ 480,00
  2. 🚌 Transporte      R$ 320,00
  3. 🏠 Moradia         R$ 250,00
  4. 🎮 Lazer           R$ 150,00
  5. 📺 Assinaturas     R$ 89,90
  6. 🏪 Mercado         R$ 0,00
────────────────────────
🔝 *Top 3:* Alimentacao, Transporte, Moradia

Last Transactions

📋 *Ultimos 5 Lancamentos*
────────────────────────
🟢 10/05  +R$ 5.000,00    Salario
🔴 10/05  -R$ 89,90       Netflix
🔴 09/05  -R$ 250,00      Jantar no centro
🔴 08/05  -R$ 35,00       Uber
🔴 07/05  -R$ 480,00      Mercado
────────────────────────

PDF Import Preview

📄 *Extrato Bancario Encontrado*
────────────────────────
🆕 02/05  R$ 150,00  🛒 Mercado
🆕 03/05  R$ 35,00   🚌 Uber
🆕 05/05  R$ 89,90   📺 Netflix
🆕 07/05  R$ 480,00  🛒 Mercado
🆕 08/05  R$ 250,00  🍔 Restaurante
🆕 10/05  R$ 5.000   📌 Salario
────────────────────────
*6 transacoes encontradas*
Deseja importar todas? (sim / nao / editar)

Goal Progress

🎯 *Meta: Viagem para Europa*
────────────────────────
💰 Meta:       R$ 8.000,00
💵 Guardado:   R$ 3.200,00
📊 Progresso:  ████░░░░░░  40%
📅 Prazo:      Dezembro 2026
────────────────────────
💡 Faltam R$ 4.800,00 em 7 meses
   (~R$ 686/mes para atingir)

Bank Statement Parsing (PDF)

Required System Dependency

apt install poppler-utils

Extraction Pipeline

1. User sends PDF or requests import
2. Agent saves file to: finance/imports/statement_YYYYMMDD_HHMMSS.pdf
3. Agent runs: pdftotext "finance/imports/statement_*.pdf" -
4. LLM parses the raw text output
5. Agent extracts structured transactions from the text

Parsing Strategy

Common bank statement formats contain:

• Date columns: 02/05 or 02 Mai or 2026-05-02
• Description: merchant name, transaction type
• Amount: positive for credits, negative for debits, or in separate columns
• Balance: running balance (should be ignored)

The agent should:

1. Recognize date patterns in the text
2. Extract each transaction line
3. Separate description from amount
4. Identify debits (negative) vs credits (positive)
5. Infer categories from descriptions
6. Filter out header/footer lines and balance rows
7. Present to user for confirmation before saving

Safety Rules

• Never save transactions without user confirmation
• Show preview with count and total amount
• Allow user to cancel or edit before import
• Avoid importing duplicate transactions (check existing by date+amount+description)

Heartbeat Integration

Add to HEARTBEAT.md in the workspace:

## Financeiro (todo dia as 20:00)
Se houver transacoes hoje, pergunte se o usuario quer o resumo do dia.

## Financeiro Mes (todo dia 1 as 09:00)
1. Processar despesas recorrentes de config.json
2. Enviar relatorio mensal do mes anterior

Usage Examples

Adding expenses

User: "gastei 35 reais em uber" Agent:

💰 Picoclaw Finance — Transacao Registrada
────────────────────────
🔴 Despesa   R$ 35,00
📂 Categoria Transporte
📝 Descricao Uber
📅 Data      11/05/2026
────────────────────────
💡 Dica: Para ver seu resumo, digite "resumo do mes"

Importing PDF

User: sends bank_statement.pdf Agent:

📄 Processando extrato bancario...

Agent processes via pdftotext, then:

📄 Extrato Bancario Encontrado
────────────────────────
🆕 01/05  R$ 5.000,00  📌 Salario
🆕 02/05  R$ 350,00    🛒 Mercado
🆕 03/05  R$ 45,00     🚌 Uber
🆕 05/05  R$ 89,90     📺 Netflix
🆕 07/05  R$ 120,00    🍔 Restaurante
🆕 10/05  R$ 200,00    🎮 Lazer
────────────────────────
*6 transacoes encontradas*
Total: R$ 5.804,90 (R$ 5.000 credito / R$ 804,90 debito)
Deseja importar? (sim / nao / editar)

User: "sim" Agent:

✅ 6 transacoes importadas com sucesso!

📊 Saldo atual do mes: R$ 4.195,10

Monthly check

User: "resumo do mes" Agent:

💰 Resumo Financeiro — Maio/2026
────────────────────────
📌 Receitas     R$ 5.000,00
💳 Despesas     R$ 1.230,00
📊 Saldo       +R$ 3.770,00
────────────────────────
📂 Por Categoria:
  🍔 Alimentacao    R$ 480,00  ████████░░
  🚌 Transporte     R$ 320,00  █████░░░░░
  🎮 Lazer          R$ 150,00  ██░░░░░░░░
  📺 Assinaturas    R$ 89,90   █░░░░░░░░░
────────────────────────
📈 Orcamento: 41% utilizado (R$ 1.230 / R$ 3.000)

Budget alert

When a new expense pushes a category over budget or total over 80%:

⚠️ *Alerta de Orcamento*
────────────────────────
Voce ja gastou 85% do orcamento deste mes!
R$ 3.825 de R$ 4.500 utilizados.
Ainda faltam 20 dias para acabar o mes.

Error Handling

Telegram Markdown Formatting Rules

• Use *text* for bold (headings, labels, currency amounts)
• Use _text_ for italic (optional notes)
• Use backticks for inline code (IDs, technical info)
• Use emoji as visual cues (💰 📊 🔴 🟢 🎯 ⚠️ 💡)
• Use ──────────────────────── (unicode) as dividers
• Keep lines under 40 characters when possible for mobile
• Progress bars: use █ filled + ░ empty (10 blocks = 100%)
• Currency format: R$ 1.234,56 (BRL standard)