legdger · Encrypted local-first ledger

$

The data is yours; the AI is just a finance copilot living on your device.

Design

Design decisions

Why this tool is built the way it is, and what that buys.

Two platforms, two jobs

iOS is the quick-entry bookkeeper; macOS is the full data terminal hosting the plugin system, AI access and batch consolidation.

A century kernel

One unified bag model, legs summing to zero per currency, and a three-verb validation gate on opening entries — once settled, the data model is never overturned.

Sync design

UUIDv7 primary keys + HLC versioning + entity-state mirror sync; the server keeps only the latest ciphertext and accumulates no history.

AI access

ledger-cli opens the local store read-only; tokens are issued and revoked by the Mac app, with an audit log attached.

Highlights

Capabilities at a glance

Local-first with on-device AI: statistics, Q&A and chat all run on the device
Double-entry kernel: an entry is a set of legs summing to zero, and balances are always derived, never stored
Eleven wallet bag types: assets, liabilities, securities, crypto holdings, reconciliation and split accounts
On-device receipt OCR: Vision parsing → rules engine → confirmation card
Native App Intents and Shortcuts: log an entry in one sentence
ledger-cli: a read-only CLI with token authorization for external AI agents to analyse safely

Metrics

Design metrics

Each one maps to a concrete decision in the implementation.

plaintext data stored in the cloud

0

Entries are encrypted on the machine; the cloud only keeps the latest ciphertext

wallet bag types

11 types

Assets, liabilities, securities, crypto holdings, pending reconciliation, split intermediates and more

kernel tests

127+

LedgerCore is a standalone Swift package with full kernel test coverage

stored balance fields

0

Balances are always derived from legs; no cached value can drift out of sync

sync payload

latest only

Entity-state mirror sync; the server accumulates no history

AI data egress

on-device

Statistics, Q&A and chat all complete on the device

Platforms

Platform support

With kernel and shell separated, support levels can advance independently per platform.

macOS

Full

The full data terminal: plugin system, AI access and batch consolidation

iOS

Full

Quick-entry bookkeeping with App Intents, Shortcuts and widgets

CLI

Full

Read-only commands with JSON output, built for agents

Windows

Planned

The kernel is designed cross-platform; the shell is not yet scheduled

Android

Planned

Same kernel; on-device AI depends on platform capability adaptation

Comparison

How it differs from the common approach

The difference usually is not in the feature table — it is in where the boundary is drawn.

Where data lives

Local-first with on-machine encryption; the cloud only ever holds ciphertext

Entries stored in the cloud in plaintext; privacy depends on the provider

Balance consistency

Double-entry: legs sum to zero per currency, balances derived and never stored

Balance stored as a column, kept consistent by code on every change

AI capability

On-device model inference, data never leaves the device; automatic fallback to the rules engine when the model falls short

Upload the ledger to the cloud for analysis

External access

Read-only CLI + token authorization + audit log; AI can read, never write

Either fully closed, or the full dataset exported to a third party

Where payment starts

Local capability free forever; only sync requires an account and payment

Core features behind a subscription, with data export billed extra

Commands

Commands at a glance

For the full manual, see the CLI reference page. All commands output structured results by default.

Full command table

ledger-cli doctor

Self-check: store location, read-only state, kernel version and encryption status

--json

ledger-cli stats

Monthly income and expense, net worth and wallet distribution

--month YYYY-MM--wallet <id>

ledger-cli wallets

List wallets and their bag types (assets / liabilities / securities / crypto holdings, etc.)

ledger-cli query

Search entries by tag, time range and amount range

--tag <tag>--from--to--min

In Practice

Actual output

ledger-cli

01$ ledger-cli doctor
02{ "ok": true, "store": "ledger-mac.store", "readonly": true }
03
04$ ledger-cli stats --month 2026-09
05{ "monthExpense": 12483.20, "monthIncome": 32000.00,
06  "netWorth": 486210.55, "wallets": 7 }

Source

Modules

3 groups, 10 modules — all from the repository’s real directory structure.

SwiftUI · SwiftData · Swift 6 · FoundationModels · Vision · GRDB (V1) · CLI

Kernel packages

LedgerCore is a standalone Swift package; the app and the CLI share one implementation.

LedgerCore

The double-entry kernel: legs sum to zero, balances derived, a three-verb validation gate on opening entries

LedgerCore/Sources/LedgerCore

LedgerCoreStorage

Storage: SwiftData models and local-store reads; the CLI opens read-only

LedgerCore/Sources/LedgerCoreStorage

LedgerCoreCrypto

Encryption: storage encrypted on the machine; only ciphertext reaches the cloud

LedgerCore/Sources/LedgerCoreCrypto

LedgerCoreSync

Sync: UUIDv7 primary keys + HLC versions + entity-state mirror sync

LedgerCore/Sources/LedgerCoreSync

Both platforms & extensions

iOS for quick capture; macOS is the full data terminal.

ledger-ios

iOS: the main bookkeeping entry, App Intents and Shortcuts, widgets

ledger-ios/

ledger-mac

macOS: the full data terminal, plugin system and batch consolidation

ledger-mac/

Intelligence

On-device intelligence: FoundationModels inference + rules-engine fallback + Vision OCR receipt recognition

ledger/Intelligence

Import / LAN

Data import (standard formats) and a LAN sync channel

ledger/{Import,LAN}

AI access

Let external agents read your ledger safely — read-only.

ledger-cli

Read-only CLI: doctor / stats and friends, with JSON output for AI agents

ledger-cli/Sources/ledger-cli

Token authorization

Tokens are issued and revoked by the Mac app, with an audit log attached

ledger-mac/

Go Deeper

Go deeper

Usage4 typical scenarios with step-by-step instructions

Modules3 module groups and what each owns

Architecture6 architecture layers and runtimes

CLI reference6 commands with their flags

Use Cases

Usage

4 typical scenarios, each broken into steps you can follow.

Log an entry in one sentence

Record an entry through App Intents and Shortcuts, without opening the app.

1Tell Siri or a Shortcut: “log an entry — lunch, 38”
2The on-device rules engine parses amount, category and time
3The matching wallet and bag type are resolved, producing a set of legs that sums to zero
4A confirmation card shows the parsed result; confirming commits it

Snap a receipt into the books

On-device OCR reads the receipt; nothing ever leaves the device.

1Take a photo or pick a receipt image from the library
2The Vision framework performs on-device text recognition
3The rules engine extracts merchant, amount and date
4A confirmation card is generated; after a human check it is committed

On-device AI finance Q&A

Ask “how much did dining cost this month” — the answer is computed on the device.

1FoundationModels inference on-device understands the natural-language question
2The kernel translates the question into a read-only query over the local ledger
3Statistics are computed on the device, with no network requests
4When the model falls short it degrades to the rules engine, so the feature stays available

Let an external agent analyse the ledger

Read-only authorization plus an audit log: AI can look, never modify.

1Generate an access token in the Mac app
2The agent opens the local store read-only through ledger-cli
3Structured JSON output is handed to the agent for analysis
4Every call is written to the audit log, and the token can be revoked at any time

Boundaries

Data boundary and security

Much of the value of this kind of tool is in what it does not do. Every item below notes where it is implemented.

On-machine encrypted storage

Entries are encrypted on the machine; the cloud keeps only the latest ciphertext, and the server never sees plaintext.

LedgerCoreCrypto

Read-only access

ledger-cli opens the local store read-only; any write is rejected at the storage layer.

ledger-cli doctor → readonly: true

Revocable tokens

Access tokens are issued and revoked by the Mac app, with an audit log attached — cut off at any time.

ledger-cli token revoke

On-device AI

Statistics and Q&A complete on the device; AI analysis never sends data out.

FoundationModels · Intelligence

A stable data model

The opening-entry transaction passes a three-verb validation gate; once settled, the data model is never overturned.

LedgerCore validation gate

Minimal sync

Entity-state mirror overwrite sync; the server accumulates no history, shrinking the exposure surface.

LedgerCoreSync

Roadmap

Release cadence

Shipped items state what was delivered; in-progress items state what is being built.

v0.6ReleasedKernel

Double-entry kernel with legs summing to zero
Eleven wallet bag types
SwiftData local storage and the encryption layer
iOS bookkeeping app with App Intents

v0.9ReleasedIntelligence & access

On-device AI statistics and Q&A
Vision OCR receipt recognition
ledger-cli read-only access and tokens
The macOS full data terminal

v1.0In developmentSync & plugins

UUIDv7 + HLC entity-mirror sync ships
The plugin system opens to third-party AI
Batch consolidation and reconciliation workflows
Multi-currency rates and conversion

v1.2PlannedExpansion

Windows / Android apps
Shared ledgers and family collaboration
Portfolio analysis views
A standard-format import/export ecosystem

FAQ

No. Entries are stored encrypted on the machine; only when sync is switched on does the latest ciphertext get uploaded — the server keeps no plaintext and accumulates no history. AI statistics and Q&A complete entirely on the device.

Source Modules

Modules

3 groups, 10 modules. Paths map directly to repository directories, so engineers can locate code fast.

Kernel packages

LedgerCore is a standalone Swift package; the app and the CLI share one implementation.

LedgerCore

The double-entry kernel: legs sum to zero, balances derived, a three-verb validation gate on opening entries

LedgerCore/Sources/LedgerCore

LedgerCoreStorage

Storage: SwiftData models and local-store reads; the CLI opens read-only

LedgerCore/Sources/LedgerCoreStorage

LedgerCoreCrypto

Encryption: storage encrypted on the machine; only ciphertext reaches the cloud

LedgerCore/Sources/LedgerCoreCrypto

LedgerCoreSync

Sync: UUIDv7 primary keys + HLC versions + entity-state mirror sync

LedgerCore/Sources/LedgerCoreSync

Both platforms & extensions

iOS for quick capture; macOS is the full data terminal.

ledger-ios

iOS: the main bookkeeping entry, App Intents and Shortcuts, widgets

ledger-ios/

ledger-mac

macOS: the full data terminal, plugin system and batch consolidation

ledger-mac/

Intelligence

On-device intelligence: FoundationModels inference + rules-engine fallback + Vision OCR receipt recognition

ledger/Intelligence

Import / LAN

Data import (standard formats) and a LAN sync channel

ledger/{Import,LAN}

AI access

Let external agents read your ledger safely — read-only.

ledger-cli

Read-only CLI: doctor / stats and friends, with JSON output for AI agents

ledger-cli/Sources/ledger-cli

Token authorization

Tokens are issued and revoked by the Mac app, with an audit log attached

ledger-mac/

Stack

Tech stack

SwiftUISwiftDataSwift 6FoundationModelsVisionGRDB (V1)CLI

Architecture

Layered design

From kernel to shell — what each layer owns and what it is built with. The core design of these tools is separating kernel from shell.

01Domain model

Four entities — Ledger / Wallet / Transaction / Term — plus the Leg value object

02Bookkeeping kernel

Double-entry legs sum to zero; balance = opening + Σ bag legs, derived on the spot

03Intelligence layer

FoundationModels on-device inference + rules-engine fallback + Vision OCR

04Sync layer

UUIDv7 identity + HLC versions + entity-mirror overwrite sync (V1)

05Access layer

The ledger-cli read-only CLI, token authorization and JSON output for AI agents

06Runtime

SwiftUI · SwiftData · Swift 6 · iOS 17.6+ · macOS

Platforms

Multi-platform support

One kernel; a different platform is just a different shell. Support levels can advance per platform.

macOS

Full

The full data terminal: plugin system, AI access and batch consolidation

iOS

Full

Quick-entry bookkeeping with App Intents, Shortcuts and widgets

CLI

Full

Read-only commands with JSON output, built for agents

Windows

Planned

The kernel is designed cross-platform; the shell is not yet scheduled

Android

Planned

Same kernel; on-device AI depends on platform capability adaptation

Stack

Tech stack

SwiftUISwiftDataSwift 6FoundationModelsVisionGRDB (V1)CLI

CLI Reference

Command reference

6 commands. Design premises: structured output and semantic exit codes, so both scripts and AI agents can consume them reliably.

ledger-cli doctor

Self-check: store location, read-only state, kernel version and encryption status

--json

ledger-cli stats

Monthly income and expense, net worth and wallet distribution

--month YYYY-MM--wallet <id>

ledger-cli wallets

List wallets and their bag types (assets / liabilities / securities / crypto holdings, etc.)

ledger-cli query

Search entries by tag, time range and amount range

--tag <tag>--from--to--min

ledger-cli export

Structured export for external AI agents to consume

--format json|csv--month

ledger-cli token

Inspect or revoke access tokens (revocation requires confirmation in the Mac app)

listrevoke <id>

Output

Output conventions

The CLI is an interface for programs; humans being able to read it is a side effect.

Structured output

JSON by default, with stable field names. Human-readable formatting is the caller’s decision, not something the CLI guesses.

Semantic exit codes

Success, failure and usage errors return distinct exit codes, so scripts and agents branch on the code instead of parsing text.

Credentials never on the command line

Local token files are discovered automatically, avoiding plaintext credentials on the command line (which would land in shell history and process lists).

Example

One real invocation

ledger-cli

01$ ledger-cli doctor
02{ "ok": true, "store": "ledger-mac.store", "readonly": true }
03
04$ ledger-cli stats --month 2026-09
05{ "monthExpense": 12483.20, "monthIncome": 32000.00,
06  "netWorth": 486210.55, "wallets": 7 }

legdgerEncrypted local-first ledger

Design decisions

Capabilities at a glance

Design metrics

Platform support

How it differs from the common approach

Commands at a glance

Actual output

Modules

Go deeper

Usage

Data boundary and security

Release cadence

FAQ

Modules

Tech stack

Layered design

Multi-platform support

Tech stack

Command reference

Output conventions

One real invocation

Hand the complexity of identity, agents and private domain to one governable kernel