--- title: Cashbox (side-project finance plugin) --- # Cashbox — money in, money out and profit for your side projects ## 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/`, 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=&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`.