A PWA for keeping hledger journals in a GitHub repository.
The goal is a fully client-side application: the journal is parsed and reported by hledger's own logic compiled to WebAssembly, served as static assets from Cloudflare Pages, with no backend. That keeps the running cost near zero, which is what makes it possible to offer the service free of charge and free of ads.
The UI is built with SolidJS, Solid Router, TailwindCSS and Kobalte. Components adapted from solid-ui are vendored into the source tree rather than taken as a runtime dependency.
Western bookkeeping reached Japan under a borrowed name. In 1873, Fukuzawa Yukichi translated Bryant and Stratton's Common School Book-keeping and published it as 帳合之法, Chōai no Hō — the method of chōai. He did not coin the word for the occasion: chōai was already what the merchant houses called the work of setting the books against what was there until the two agreed. Double-entry arrived in the country under a name it found waiting for it, imported whole rather than invented anew.
This is the same kind of carrying across. The accounting here is hledger's own, compiled and brought into the browser intact, not reimplemented in it. So the app is named for the crossing rather than for the cargo: choai.
The journal is kept as the text file it is, and hledger itself -- compiled to WebAssembly and running in a worker -- reads it and answers every question the screens ask. Nothing is uploaded anywhere by the app.
- Read: the daily journal, the balance sheet, the income statement, and a trial balance -- every account the books have, in the two columns they are checked in. One hledger query applies to whichever is open.
- Write: entries are composed beside the journal, with accounts suggested
from what the books already contain -- by the same code
hledger adduses -- and a posting left blank for hledger to work out. Text is appended, never rewritten. - Edit: the journal's own text, one file at a time. hledger reads it before it is kept, so text that will not parse never replaces text that does.
- Keep: the files stay on the device, one record per path, and the journal left open comes back on the next visit.
- Take away: the share sheet on a phone, a download elsewhere.
- Import: photographs of receipts, read into entries. The text is read off the picture in the browser, each row is sorted by Jev — a model that answers with probabilities and writes nothing — and the figures are checked against each other before a total is believed. Entries are offered rather than written: what is confident is ticked, what is not carries its reason, and nothing joins the journal until you press. Jev is reached through OpenRouter with a key of your own; the photograph itself never leaves the device.
- Talk: there is no conversation in the app. Bring an agent: it reads
window.choai.describe()— what it may call, and how to use it with somebody's books — and works through the same table the screens use. - Sync: a path in a GitHub repository, reached from the browser straight to api.github.com. Entries written in two places are laid one after the other; when the same part changed on both sides, nothing is merged and it says so.
Everything above is reachable without a screen. Opening the app puts a
window.choai in the page: the same core, answering a script, a test, or an
agent instead of a person.
await window.choai.ready // which journal is open, decided
window.choai.describe() // every capability, with its JSON Schema
await window.choai.report.balance({ query: "date:lastmonth acct:expenses" })
await window.choai.call("journal.similar", { descriptions: ["Amazon", "Starbucks"] })
await window.choai.idle() // everything asked has been answereddescribe() returns a manifest with a version that names this promise. Adding
a capability, or an argument that may be left out, leaves anything already
written against it working; taking one away, or narrowing one, does not, and
that is what the version moves for.
- Two doors, one table.
choai.report.balance(...)is for names known when the code is written;choai.call(name, args)is for anything that readdescribe()and chose. Both are read off one table, so what a capability takes cannot drift from what it says it takes. - Nothing throws. Every call answers
{ok: true, value}or{ok: false, error}, and the error is a case with its particulars rather than a sentence — a missing field comes back with the path to it and the whole schema, so a correction can be made without asking again. - Figures are exact. Amounts cross as a mantissa and a scale, with the same figure written out. hledger's floating-point copy is left behind.
- Writing is two acts.
transaction.proposewrites changes down without making them and says whether hledger read the result;proposal.applykeeps them, or the ones named and no others. Taking an entry out is a proposal like putting one in — an addition nobody wanted can be deleted afterwards, a deletion nobody wanted is gone — so a correction is a removal and an addition shown together and written at once. A diff exists before anything is decided, a hundred entries with three doubtful ones is one glance and one press, and a proposal made against a journal that has since moved is refused rather than applied over the top of it. - What is deliberately absent. No way to run code, no way to write a file as text, and no way to read back the tokens this app keeps. A capability names an act, and the acts are the ones the screens also perform — so an agent goes through the same door as a person, and hledger reads everything before it is kept.
Being reachable is the point: this is a local application with no server, and
what it can do it can be asked to do. So it says so where something that is not
a person would look: std.choai.dev/llms.txt and choai.dev/llms.txt, and a
line on the console when the app loads. None of the three writes the capability
list down — they point at describe(), which is derived from the one table and
cannot disagree with what runs.
The feasibility spike that decided all this lives in wasm/; its
answer -- that hledger-lib can be compiled to wasm32-wasi, kept small enough
for a Cloudflare Pages asset, kept fast enough to be usable, and kept close
enough to upstream to follow future releases -- is recorded with its
measurements in wasm/RESULTS.md. See wasm/README.md for how to reproduce
them.
Not one line of hledger's source is modified. What we write is the binding that
exports its functions to JavaScript, in wasm/hledger-wasm/src/Bindings.hs.
The app is built twice from one source tree. std.choai.dev is the standard
edition and jp.choai.dev the Japan edition — the same core, the same
screens, and somewhere for Japanese tax work to go without any of it reaching
the books everyone else keeps.
The dependency runs one way:
standard ─┐
├──> core
jp ───────┘
apps/web/src has four directories and no loose files:
src/
├── core/ plain text accounting. Belongs to nowhere and knows of no edition
├── edition/ the contract (types.ts), the roll, and the door core knows one by
├── editions/ standard/ and jp/, one module each
└── app/ the entry, the shell, and the table of every screen there is
Core is plain text accounting: the journal, hledger, the reports, the screens,
window.choai. It has no idea Japan exists, and there is no if (edition ===
anywhere in it. What an edition adds is two tables and nothing else —
src/edition/types.ts:
views— screens with an address of their own and a place on the rail. The door a person comes through.capabilities— the same thing offered by name, described bydescribe()and given to a model as a tool by the same rules as everything else. The door a script or an agent comes through.
An edition adds; it cannot replace or take away. A view at an address core already has is dropped, and a capability core already names stays core's, so no edition can quietly change what a balance sheet means.
Which one a build is comes from CHOAI_EDITION, never from anything the running
app asks:
bun run build # the standard edition — the default
bun run build:standard # the same, said out loud
bun run build:jp # the Japan edition
bun run dev:jp # and the same while developing~/edition/chosen is a name with no file behind it, and vite.config.ts points
it at whichever edition was named, so the other one's code is not in the bundle
at all rather than in it and unreachable — a standard build carries no Japanese tax law even after there is
some to carry. A CHOAI_EDITION it does not recognise stops the build rather
than falling back, because the fallback would be a standard build published at a
name that promised something else.
The Japan edition adds five screens and five capabilities, and every one of them follows one division: what the books say, and what Japanese tax makes of it. A date, a debit and an amount are the same in every country and are core's. A consumption tax band, a useful life, the heading an account prints under — each follows the rules of a year and the practice of a company, can change without a single entry changing, and is written into the journal as a tag rather than inferred from an account's name. Every screen there draws that line across the middle of itself, so a figure says which of the two it came from.
Nothing it adds writes an accounting entry. Depreciation and the year-end
adjustments come out as proposals — read by hledger, shown as the text they would
become, kept only when somebody presses core's own button. What it does write is
ordinary hledger: account directives, and a plain text asset register beside
the journal that the journal itself declares.
What it deliberately does not work out — the taxable base, the tax payable, the
simplified basis, how the year of a disposal is treated — is listed in
apps/web/src/editions/jp/README.md, with
why. Each is a decision a company makes and can be wrong about, and a figure
worked out silently would look filed-in without being it. Corporate tax returns
and e-Tax are not built; e-Tax is a submission protocol and stays one.
Which edition you have open is on the manifest — describe().edition — and on
the one line the app writes to the console.
The rules this is added under — what core may never do, what is deliberately
not built, and the checks that say the boundary has broken — are in
apps/web/src/edition/README.md, beside the
code they govern.
choai.dev— the page that explains the app, fromlp/dist: a separate Astro project, English at the root and Japanese at/ja/. It loads no fonts and ships no script of its own.std.choai.dev— the app itself as the standard edition, fromapps/web/dist.jp.choai.dev— the same app built as the Japan edition, from the same directory:bun run build:jpand thewrangler.jp.jsoncbeside it.
docs.choai.dev is where the explaining page used to be, and every path on it
is sent permanently to the same path on choai.dev.
The names are counted by the host as it serves them, rather than by anything written into any of them: page views, and where they were reached from. Nothing is kept on the device to recognise a return by, so there is no monthly total and nobody is followed from one name to the next — which is the counting the privacy page describes, on the app's behalf as well as its own.
scripts/build-site.sh builds the app and the landing page locally; the Japan edition
is bun --cwd=apps/web run build:jp, which writes to the same apps/web/dist.
Each is published on its own as a Cloudflare Worker serving static assets, built
from this repository on a push to main. What the directory is and how it is
served is in the wrangler.jsonc beside it — wrangler.jp.jsonc for the Japan
edition, which is the same file but for the worker's name. The rest lives in the
dashboard, where each is configured the same way but for its own directory and
its own build:
choai |
choai-jp |
choai-docs |
|
|---|---|---|---|
| Root directory | apps/web |
apps/web |
lp |
| Build command | bun install && bun run build |
bun install && bun run build:jp |
bun install && bun run build |
| Deploy command | bunx wrangler deploy |
bunx wrangler deploy -c wrangler.jp.jsonc |
bunx wrangler deploy |
BUN_VERSION |
1.3.14 |
1.3.14 |
1.3.14 |
| Custom domain | std.choai.dev |
jp.choai.dev |
choai.dev |
No output directory is set in any of them, because assets.directory already says
it. Nothing else is needed: the engine is committed, so the build wants no
Haskell toolchain, and lp needs no PUBLIC_APP because a build that is not
a development one already points at the published app.
The names are attached in the dashboard, on the worker's own Domains & Routes,
and each name's record is written by attaching it. They are deliberately not in
the wrangler.jsonc files, though a routes entry would put them there: a name
is not part of what this software is, only of where this one copy of it happens
to live. Anyone is free to run their own, and a wrangler deploy that opened by
demanding a domain somebody else owns would refuse to do anything at all.
The move from docs.choai.dev is the same kind of fact, so it is kept in the
same place: a Single Redirect rule on the choai.dev zone (Rules → Redirect
Rules), not a Worker. Nothing is served on that name any more, only answered
with where to go instead, and a Worker written to do it would be the one piece of
server code in a project that has none — and would send somebody else's copy to
ours.
| When | Hostname equals docs.choai.dev |
| Then | Dynamic, concat("https://choai.dev", http.request.uri.path) |
| Status | 301 |
| Query string | preserved |
The rule only runs where Cloudflare is answering, so the name keeps a proxied
DNS record of its own once it is detached from choai-docs: an AAAA to 100::,
which points nowhere and is never reached.
GPL-3.0-or-later.
This is not a preference so much as a consequence: the application ships hledger-lib compiled into its WebAssembly module, and hledger is GPL-3.0-or-later, so the combined work is too. Publishing the source here is what satisfies the corresponding-source obligation for the binary that browsers download.
apps/web/src/core/lib/solid-workbench-shell is the author's own work under MIT, which
is compatible with the above and leaves it reusable outside this project.
Components under apps/web/src/core/components/ui are adapted from
solid-ui (MIT). Icons are from
lucide (ISC).