agentbudget

Agentbudget is a high-precision, agent-first command-line interface designed for zero-based envelope budgeting. It enables developers and power users to automate personal finance workflows using structured SQLite or Turso/libSQL databases. Built with TypeScript and Drizzle ORM, it offers a robust framework for managing accounts, envelopes, payees, and transactions with a focus on programmatic automation via JSON output.

• Zero-based budgeting: Enforce strict envelope allocation to track every dollar or currency unit assigned to categories.

• Agent-first architecture: Primary interface supports --json flags, returning machine-readable objects for integration with LLM agents or automation scripts.

• Flexible backend: Native support for local SQLite files and remote Turso (libSQL) databases for cross-device syncing.

• Transaction management: Automated payee rule resolution, split transaction support across envelopes, and detailed reconciliation tools.

• Currency handling: Intelligent conversion and formatting support, strictly distinguishing between major units (input) and minor units (internal storage).

• Schedule and Reporting: Built-in overview commands to visualize monthly cash flow, balances, and top spending categories.

• Input format: CLI commands accept major units (e.g., 23.50), while JSON outputs provide data in minor integer units (e.g., 2350) to prevent floating-point drift.

• Security: Uses standard environment variables like TURSO_DATABASE_URL and TURSO_AUTH_TOKEN for configuration.

• Workflow: Typical usage involves initializing the DB, defining accounts, setting currency, and then batch importing transactions via JSONL files.

• Error handling: Provides consistent JSON error responses with status codes, making it ideal for robust automation pipelines.

• Constraints: Strictly requires Node.js 20+; ensures data integrity by handling migrations automatically via Drizzle.