Friday

Friday is a self-hosted personal finance agent. It tracks expenses and syncs investment portfolios from Telegram or Slack, auto-ingests bank alerts and broker statements from email, and writes the results into Actual Budget and Portfolio Performance.

Friday runs on Hermes Agent in a Docker Compose stack. The agent’s name, emoji, vibe, and voice are supplied at deploy time through IDENTITY_NAME, IDENTITY_EMOJI, IDENTITY_VIBE, and the SOUL_VOICE_* variables, then rendered into SOUL.md from modules/hermes/SOUL.md.template.

What it does

• Expense tracking. Watches a mailbox over IMAP, classifies each message, and books transactions into Actual Budget. In chat, you can also ask Friday to look up accounts, check duplicates, or record a purchase directly.
• Portfolio tracking. Imports IBKR Flex queries and PDF trade confirmations, keeps Portfolio Performance balances in sync with Actual Budget, and exports taxonomies to Google Sheets.
• Two chat channels. Telegram (Bot API) and Slack (Socket Mode, an outbound WebSocket, so no inbound port is required).
• One agent, many tools. Hermes connects to both trackers as MCP servers and as plain REST services, so chat requests and automated email workflows share the same tool surface.

Architecture

graph TB
    USER["Telegram / Slack user"]

    subgraph Docker["Docker Compose (modules/docker-compose.yml)"]
        HERMES["hermesHermes Agent — gateway run:8642 :9119 :8644WebUI 127.0.0.1:8787"]

        ET["expense-trackerNode.js — :8080REST /tools/* + MCP /mcp"]
        PT["portfolio-trackerNode.js — :8081REST /tools/* + MCP /mcp"]
        ACT["actual-apiNode.js — :3000"]
        ROUTER["codex-router:4100 — /v1"]
    end

    USER -->|"Telegram Bot API"| HERMES
    USER -->|"Slack Socket Mode"| HERMES
    HERMES -->|"replies"| USER

    HERMES -->|"MCP http://expense-tracker:8080/mcp"| ET
    HERMES -->|"MCP http://portfolio-tracker:8081/mcp"| PT
    HERMES -->|"LLM responses http://codex-router:4100/v1"| ROUTER

    ET -->|"REST"| ACT
    PT -->|"REST"| ACT
    ET -->|"LLM responses via LLM_BASE_URL"| ROUTER
    PT -->|"LLM responses via LLM_BASE_URL"| ROUTER

    MAIL["Bank / broker emailIMAP :993"]
    MAIL -->|"IMAP IDLE"| ET
    MAIL -->|"IMAP IDLE"| PT

    ACT -->|"WebSocket sync"| AB["Actual Budget server"]
    PT -->|"Java CLI reads/writes"| PP["Portfolio Performance XML"]
    PT -->|"pp-pull / pp-push (Microsoft Graph)"| OD["OneDrive"]
    PT -->|"update_google_sheet"| GS["Google Sheets"]
    ROUTER -->|"HTTPS"| DS["DeepSeek API"]

    WEBHOOK["Hermes webhook :8644"]
    ET -->|"notify_user"| WEBHOOK
    PT -->|"notify_user"| WEBHOOK
    WEBHOOK --> HERMES