Kotlin Multiplatform implementation of Beancount v3.2.3, compatible with JVM, Android, iOS, and Kotlin.

Beancount JVM is a complete migration of Python Beancount accounting system to the JVM/Android ecosystem using Kotlin Multiplatform (KMP). It maintains semantic compatibility with Python Beancount 3.2.3 while delivering up to 2.2x performance improvement on large ledgers.

• Full Compatibility: Parses and processes all valid Beancount v3.2.3 files
• High Performance: Up to 2.2x faster than Python on large ledgers (see benchmarks)
• KMP Targets: JVM, Android (minSdk 21), and iOS (arm64 + simulator)
• Zero Runtime Dependencies: Core library only needs kotlinx-datetime and okio
• Bilingual API: Kotlin-first with Java-compatible static methods via @JvmStatic
• Complete CLI: All Python beancount commands (bean-check, bean-doctor, bean-format, etc.)
• Query Engine: Full BQL (Beancount Query Language) implementation

Published to Maven Central and discoverable on klibs.io.

For KMP projects (commonMain):

// build.gradle.kts (KMP project)
commonMain.dependencies {
    implementation("io.github.tonyzhye:beancount-core:3.2.5")
}

For JVM-only projects:

// build.gradle.kts (JVM project)
dependencies {
    implementation("io.github.tonyzhye:beancount-core:3.2.5")
}

For Android projects:

// build.gradle.kts (Android project)
dependencies {
    implementation("io.github.tonyzhye:beancount-core:3.2.5")
}

For Maven (JVM-only):

<dependency>
    <groupId>io.github.tonyzhye</groupId>
    <artifactId>beancount-core-jvm</artifactId>
    <version>3.2.5</version>
</dependency>

import io.github.tonyzhye.beancount.api.Beancount as bn

// Load a beancount file
val result = bn.loadFile("ledger.beancount")

// Check for errors
if (result.errors.isNotEmpty()) {
    println(bn.formatErrors(result.errors))
    return
}

// Query all transactions
val transactions = bn.getTransactions(result.entries)

// Get all accounts
val accounts = bn.getAccounts(result.entries)

// Build price map
val priceMap = bn.buildPriceMap(result.entries)

// Format entries back to beancount syntax
println(bn.formatEntries(result.entries))

import io.github.tonyzhye.beancount.api.Beancount;
import io.github.tonyzhye.beancount.core.LoadResult;

// Load a beancount file
LoadResult result = Beancount.loadFile("ledger.beancount");

// Check for errors
if (!result.getErrors().isEmpty()) {
    System.out.println(Beancount.formatErrors(result.getErrors()));
    return;
}

// Get all accounts
var accounts = Beancount.getAccounts(result.getEntries());
System.out.println("Accounts: " + accounts);

# Check a ledger file
beancount check ledger.beancount

# With verbose output
beancount check ledger.beancount --verbose

# Format/beautify a file
beancount format ledger.beancount -o formatted.beancount

# Run BQL queries
beancount query ledger.beancount "SELECT date, narration, position WHERE account ~ 'Expenses'"

# Show file dependencies
beancount deps ledger.beancount

# Get help for any command
beancount check --help

┌─────────────────────────────────────────────────────────────┐
│                         CLI Layer                            │
│   bean-check | bean-doctor | bean-format | beanquery        │
├─────────────────────────────────────────────────────────────┤
│                      API Layer                               │
│              Beancount singleton (60+ methods)              │
├─────────────────────────────────────────────────────────────┤
│                      Query Engine                            │
│   BQL Parser → Compiler → Executor (60+ functions)          │
├─────────────────────────────────────────────────────────────┤
│                      Loader Layer                            │
│   Parse → Sort → Booking → Transformations → Validation     │
├──────────────┬──────────────┬───────────────────────────────┤
│    Parser    │   Plugins    │         Core                  │
│   Lexer      │  18 Built-in │    12 Directive Types        │
│   Parser     │   Plugins    │    Amount / Cost / Posting   │
│   Booking    │              │    Inventory / Validation    │
└──────────────┴──────────────┴───────────────────────────────┘

core (foundation)
  ↑
parser (depends on core)
  ↑
loader (depends on parser, core)
  ↑
api (depends on loader, parser, query, core, plugin-api)
  ↑
cli (depends on api, loader, query)

• [x] All 12 directive types (Open, Transaction, Balance, etc.)
• [x] Full booking methods (FIFO, LIFO, HIFO, STRICT, etc.)
• [x] Complete validation suite (7 validators)
• [x] Inventory management with cost basis tracking
• [x] Display context and number formatting

• [x] Recursive descent parser with 20+ token types
• [x] All directive syntax support
• [x] Metadata and tags/links handling
• [x] Include file resolution
• [x] Plugin directive parsing
• [ ] C-extension performance (not needed - Kotlin is faster)

• [x] 18/18 built-in plugins implemented
  • auto_accounts, implicit_prices, currency_accounts
  • leafonly, unique_prices, coherent_cost
  • check_closing, check_commodity, noduplicates
  • nounused, onecommodity, sellgains
  • check_drained, close_tree, pedantic
  • auto, check_average_cost, commodity_attr

• [x] BQL parser and compiler
• [x] 60+ built-in functions
• [x] JOIN, GROUP BY, ORDER BY, PIVOT BY
• [x] Time-slicing (YEAR, QUARTER, MONTH, WEEK, DAY)
• [x] Multiple output formats (TEXT, CSV, HTML, BEANCOUNT)

• [x] bean-check - Validate ledger files
• [x] bean-doctor - Diagnostic tools
• [x] bean-example - Generate example ledgers
• [x] bean-format - Format/beautify files
• [x] beanquery - BQL query interface
• [x] treeify - Tree visualization
• [x] bean-deps - Dependency analysis
• [ ] bean-report (excluded per design)
• [ ] bean-price (excluded per design)

All 18 built-in plugins and the complete BQL query engine are implemented.

Compared against Python Beancount 3.2.3:

• 98 test classes — all PASS
• 9 end-to-end files (starter, basic, example, 50KB–10MB) — zero errors on both Python and Kotlin
• All 18 built-in plugins produce identical results

Full comparison report: CONSISTENCY_REPORT.md

Compared to Python Beancount 3.2.3 (load + book + validate):

Kotlin scales better as file size grows — from roughly equivalent on small files to 2.2x faster on 10 MB ledgers.

Full benchmark report: PERFORMANCE_REPORT.md

• JDK 21+
• Gradle 9.5+ (wrapper included)
• Android SDK (for Android target compilation)

# Build all modules (JVM + Android)
./gradlew build

# Run tests
./gradlew test

# Run Android unit tests
./gradlew testDebugUnitTest

# Generate coverage report
./gradlew koverHtmlReport

# Build CLI distribution
./gradlew :cli:distZip

# Publish to local Maven
./gradlew publishToMavenLocal

Recommended: IntelliJ IDEA with Kotlin plugin

1. Open project root (where settings.gradle.kts is)
2. Gradle will auto-sync and download dependencies
3. Run tests via IDE or ./gradlew test

# All tests (JVM + Android unit tests)
./gradlew test

# JVM tests only
./gradlew jvmTest

# Specific module
./gradlew :core:jvmTest
./gradlew :parser:jvmTest
./gradlew :loader:jvmTest
./gradlew :query:jvmTest

# Coverage verification
./gradlew koverVerify

# Compatibility tests (requires Python + beancount 3.2.3)
./gradlew :loader:jvmTest --tests "*CompatTest"

Coverage Status:

• Architecture Overview - Project structure and conventions
• CI/CD Guide - GitHub Actions setup
• Performance Report - Detailed benchmarks
• Consistency Report - Python parity verification
• Changelog - Version history

Contributions are welcome! Please read our Contributing Guide (if available) and ensure your changes:

1. Pass all tests (./gradlew test)
2. Maintain 80%+ code coverage
3. Follow existing code style
4. Include appropriate tests

This project is licensed under the GNU General Public License v2.0 only (GPL-2.0-only).

Copyright (C) 2026 Tony Ye

Based on Beancount by Martin Blais, licensed under GPL-2.0-only.

• Martin Blais - Creator of Beancount
• Beancount Community - Documentation and ecosystem
• Kotlin Team - Excellent multiplatform support

• beancount - Original Python implementation
• fava - Web interface for Beancount
• beancount-language-server - LSP implementation

This is an independent project, not affiliated with the official Beancount project.