ECON: Executive Controller & Operations Navigator

An open-source, local-first AI financial operating system for SaaS startups. It combines an auditable double-entry ledger, deterministic financial analysis, proactive forecasting, visual workflows, document ingestion, connector adapters, and a LiveKit voice advisor powered by native audio-to-audio realtime models (Google Gemini and OpenAI Realtime).

The central product idea is interaction parity: every meaningful action available through mouse and keyboard is represented by a typed command that the voice agent can call through LiveKit RPC. The agent can read, navigate, investigate, chart, and model freely. Any action that changes financial state requires human approval.

Hackathon vertical slice

The current build demonstrates:

• SaaS KPIs: MRR, ARR, month-over-month growth, gross margin, burn, and runway.
• Monthly revenue and expense analysis with visual drill-downs.
• Six- to eighteen-month revenue, expense, and cash projections.
• Scenario modeling for hiring, pricing, annual prepay, and new initiatives.
• Proactive cash-buffer, budget, cost-growth, and classification warnings.
• Budget-versus-actual analysis by operating category.
• CSV/bank-statement import with local auto-categorization.
• Receipt and invoice ingestion with Gemini or OpenAI vision and a review queue.
• Stripe, QuickBooks, and Xero connector adapters.
• A balanced double-entry journal and trial-balance health checks.
• LiveKit voice sessions with native audio-to-audio streaming (Gemini Live & OpenAI Realtime).
• Automatic local agent worker dispatching configured directly in client-side access tokens.
• LiveKit RPC forwarding from agent tools to the Electron interface.
• An offline deterministic advisor and optional local Ollama reasoning.
• Human approval and audit trails for agent-requested writes.

This is a hackathon MVP, not production accounting, tax, audit, or investment software.

Architecture

flowchart TD
    Human["Mouse, keyboard, or voice"] --> Commands["Typed finance command layer"]
    Agent["LiveKit Realtime advisor"] -->|RPC| Commands
    Commands --> UI["React financial workspace"]
    Commands --> Engine["Deterministic finance engine"]
    Commands --> Approval["Approval and audit controls"]
    Engine --> Ledger["Local double-entry ledger"]
    Connectors["CSV, Stripe, QuickBooks, Xero, images"] --> Ledger
    LocalAI["Rules + optional Ollama"] --> Commands

Loading

Trust boundaries

• The selected Realtime model (Gemini or OpenAI) interprets intent, selects tools, and explains results, while dynamic OCR parses document fields.
• The TypeScript finance engine calculates every authoritative metric and forecast.
• Only posted transactions affect statements, KPIs, budgets, and cash.
• Low-confidence imports become draft journal entries and enter a review queue.
• Each journal entry must balance before it can enter the trial balance.
• Agent-originated categorization and connector-sync commands require human approval.
• Every command records its actor, timestamp, summary, and outcome.

Technology

• Electron 38
• React 19 + TypeScript + Vite
• Zustand local persistence
• Recharts
• LiveKit Agents, LiveKit Client SDK, and LiveKit RPC
• Google Gemini Live API (gemini-2.0-flash-exp) & OpenAI Realtime API (gpt-realtime-2.1)
• Google Gemini 2.0 Flash & OpenAI Responses (gpt-5.6) APIs for OCR
• Optional Ollama-compatible local model
• Vitest

Run the desktop app

Requirements:

• Node.js 20 or newer
• npm 10 or newer

npm install
npm run dev

Production renderer build:

npm run build

Package for the current operating system:

npm run dist

Configure voice

Copy .env.example to .env.local and set:

VITE_LIVEKIT_URL=wss://your-project.livekit.cloud
VITE_LIVEKIT_TOKEN=short-lived-participant-token

LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=...
LIVEKIT_API_SECRET=...
OPENAI_API_KEY=...

For a real deployment, use VITE_LIVEKIT_TOKEN_ENDPOINT instead of placing a static participant token in the renderer environment.

Run the agent worker:

npm run agent:check
npm run agent:dev

The worker uses:

• gemini-2.0-flash-exp (default Gemini) or gpt-realtime-2.1 (default OpenAI) for low-latency audio-to-audio realtime interaction.
• LiveKit RPC method finance.execute to operate the desktop.

Connector configuration

CSV

CSV is fully local and accepts common date, description, amount, debit, credit, and category column aliases. See sample-data/transactions.csv.

Stripe

Set STRIPE_SECRET_KEY. The adapter imports Stripe balance transactions and normalizes payouts, fees, and revenue into the local model.

QuickBooks

Set QUICKBOOKS_ACCESS_TOKEN and QUICKBOOKS_REALM_ID. The MVP adapter imports purchases. Production OAuth onboarding and token refresh remain roadmap work.

Xero

Set XERO_ACCESS_TOKEN and XERO_TENANT_ID. The MVP adapter imports bank transactions. Production OAuth onboarding and token refresh remain roadmap work.

Receipts and invoices

With credentials configured, image and PDF documents are sent to Gemini 2.0 Flash or OpenAI for structured extraction. Without a key, documents stay local and enter manual review.

Offline behavior

Without internet, the app retains:

• The transaction store and balanced journal.
• Dashboards and visual drill-downs.
• MRR, ARR, growth, margin, burn, and runway calculations.
• Budget analysis, forecasts, warnings, and scenarios.
• CSV import and rule-based categorization.
• A deterministic typed advisor.

For richer local reasoning, run Ollama and configure:

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=gpt-oss:20b

Realtime voice currently uses LiveKit and therefore requires a network connection. A local Whisper/Piper voice adapter is a post-hackathon extension; the offline MVP is intentionally described as typed advisory rather than claiming offline voice that is not implemented.

Tests

npm test
npm run build
npm run agent:check

Tests cover monthly statements, SaaS metrics, cash/runway, budgets, forecasts, scenarios, CSV normalization, command permissions, balanced journal entries, and draft exclusion.

How Codex and GPT-5.6 were used

This project was designed and implemented in a primary Codex Build Week session using GPT-5.6. Codex was used to:

• Convert a broad “full startup accountant” idea into a judgeable vertical slice (ECON).
• Design the shared command/RPC architecture, dynamic token-based dispatching, and trust boundaries.
• Implement the React/Electron workspace and financial visualizations.
• Build and test the deterministic finance, forecasting, ingestion, and ledger layers.
• Implement the LiveKit agent support for both Google Gemini Live and OpenAI Realtime.
• Run compilation and domain tests, diagnose failures, and document verification steps.

GPT-5.6 is also used inside the product for:

• The LiveKit financial advisor’s low-latency realtime reasoning and tool selection.
• Multimodal receipt and invoice extraction.

The model is never the source of truth for balances, KPIs, journal arithmetic, budgets, or forecasts. Those values come from tested deterministic code.

Path from MVP to a $100M company

The architectural direction supports staged growth, but the current build does not claim production readiness at that scale. Major milestones include:

1. OAuth onboarding, webhook sync, reconciliation, and idempotent connector jobs.
2. Accrual accounting, AR/AP, deferred revenue, revenue recognition, and close workflows.
3. Multi-currency, multi-entity consolidation, departments, and cost centers.
4. Cohorts, churn, CAC, LTV, bookings, billings, and board reporting.
5. RBAC, SSO, segregation of duties, immutable audit storage, and approvals.
6. Encryption and key management, backups, observability, SOC 2 controls, and disaster recovery.
7. Accountant collaboration, exports, jurisdictional integrations, and external audit support.

License

Apache License 2.0. See LICENSE.