Cashbox (side-project finance plugin)

What it is

Cashbox answers one question for each of your side projects: did it make money? Every project shows what came in, what went out, and the profit between them, for this month, this quarter, this year or all time.

You log money the way you would say it out loud. Type "stripe payout 240 for booksum" or "paid 20 for hosting yesterday", press Enter, and the entry is saved immediately. Cashbox then reads the sentence with your AI account, works out the amount, currency, category and project, and files it. If it cannot read the sentence, your words are kept and the entry is marked as needing an amount, so nothing you type is ever lost.

Cashbox is a separate plugin from Coffer, Omniscio's personal-finance feature. It never reads or writes Coffer's data, and household money and project money are never mixed.

Turning it on

Cashbox is built into Omniscio but ships switched off. Open Settings → Plugins, find Cashbox, and switch it on. A Cashbox row (a wallet icon) appears in the sidebar; click it to open the screen.

Its two settings live on the same plugin page:

• Home currency — every project's totals are shown in this currency. The list is the 30 currencies the European Central Bank publishes rates for.
• Plain-word capture — on by default. When on, what you type is read by your AI account. When off, you type the amount, currency and category into a small form instead, and nothing is sent anywhere.

Logging money

• In plain words — type into the box at the top and press Enter (or click Add). Press / anywhere on the screen to jump to the box. On the projects screen, a picker beside the box chooses which project the entry goes to; inside a project, entries go to that project.
• As fields — click Fill in fields instead to type the direction (money in, money out or a refund), amount, currency, category, a short label and the date yourself, then press Ctrl+Enter from any field (or click Add entry). With plain-word capture off, this form is the only way in.
• Amounts accept what people normally type: 12.50, 12,50, 1 234.56, 1,234.56. An amount Cashbox would have to guess at is refused with a message, not stored.
• A refund reduces the expenses of the category it came back from; it is not counted as income.

If the AI cannot find an amount, is switched off, is not set up, or has hit its daily limit, the entry still saves with your words and a one-line note says why. Open the entry and fill in the amount yourself.

What you see

• The projects screen — this month's profit, money in and money out across everything, then one row per project with its profit this month and all time. Projects you have archived sit under their own heading. Entries that belong to no project are gathered under Unassigned.
• A project's screen — tabs for This month, This quarter, This year and All time; the profit for that window with money in and money out; a ring showing where the money went by category (switch it to money in with the toggle); a six-bar chart of the last six months' profit; the project's repeating costs; and every entry in the window, newest first.
• Profit and loss are always written as words ("Profit", "Loss", "Break-even") next to the number, never shown by colour alone.
• Entries that are not counted yet carry a label saying why: still being read, waiting for an exchange rate, or waiting for an amount. The totals say how many entries they could not count.

Currencies

Money is converted once, at the European Central Bank rate for the day the money moved (a weekend entry uses the Friday rate), and then frozen on the entry together with the rate and its date. Later rate changes never move a past total. If no rate exists for a currency and day, the entry is shown as waiting for a rate and left out of the totals rather than converted at a guess.

Changing your home currency re-converts every entry at the rate for its own day, in the background. Amounts are kept as exact whole cents (or yen, or fillér), so totals never drift by a cent.

Repeating costs

• Suggestions — when the same charge appears about a month apart three times (the same label and category, amounts within 15% of each other), Cashbox asks "Does this repeat?". Yes, it repeats turns it into a repeating cost starting from the next expected charge; No, it does not puts that suggestion away for good. Nothing is added until you say yes.
• Declaring one — open any entry and choose Make it repeat, monthly or yearly.
• Posting — each due charge is added once, including any missed while Omniscio was closed, and marked as recurring. An occurrence you delete never comes back.
• Stopping — Stop ends future charges only; everything already posted stays.
• A project's header shows what its active repeating costs come to per month, one figure per currency.

Fixing, deleting and undoing

Click any entry to open the editor; the cursor lands in its amount. It shows the words you originally typed, and lets you change the project, direction, amount, currency, category, label and date. Changing an amount, currency or date re-converts the entry. Ctrl+Enter saves from any field, and Escape closes the editor without saving and puts you back on the entry.

Deleting an entry or a project hides it and shows an Undo bar for about eight seconds (Ctrl+Z also works). Nothing is ever destroyed by one click.

Exporting

Export everything (on the projects screen) or Export (on a project) writes a CSV spreadsheet to a place you pick. Each row carries the date, project, direction, category, label, the original amount and currency, the home-currency amount, the rate and its date, who logged it, its status, whether it was deleted, and the words that were typed. It opens cleanly in Excel with accents and currency symbols intact, and a cell that would run as a formula is escaped.

For agents: the Cashbox commands

Other Omniscio sessions can read figures and log entries through three plugin commands on the local control server (http://127.0.0.1:19519/plugins/cashbox/cli/<path>, the usual bearer token). None of them calls the AI, and none edits or deletes anything.

Command	What it does
GET projects	Every live project with this month's and all-time revenue, expenses and profit in the home currency, as exact minor units plus decimal text.
GET summary?project=<id>&span=month|quarter|year|all	Revenue, expenses and profit for one project (or all, when project is omitted) over a span; month is the default.
POST entry	Logs one entry: { projectId, direction: "revenue" | "expense" | "refund", amount: "12.50", currency: "USD", label?, category?, date?: "YYYY-MM-DD" }. The amount must use . as the only decimal mark; anything ambiguous is refused with a 400 and a reason. The entry is marked as logged by an agent.

Privacy

Your projects, entries and amounts are stored only in Omniscio's local database on this computer. Two things ever leave it: the sentence you typed, sent to your AI account only when plain-word capture is on (the instructions sent with it carry none of your data, not even project names), and an exchange-rate lookup, which sends only a date. Uninstalling Cashbox removes its data with it.

What it does not do

Cashbox is a record of what a project earned and spent. Invoices, tax, receivables and splitting a shared cost across projects are outside what it does.

Where it lives (for agents working on the code)

The plugin is at src/plugins/cashbox/: a pure core shared by both halves (core/), a background worker that reads entries, converts currencies and posts repeating costs (backend/), and the screen (web/, built into ui/assets/). Its promises are in the Cashbox contract (.claude/memory/contracts/cashbox-plugin-contract.md), and the map of how the parts fit, with the traps a change tends to fall into, is .claude/memory/cashbox-map.md.