# Project pack: Actual Budget @ 27290a8

Facts about **Actual Budget** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Actual is a budgeting app built around envelope budgeting: you decide in advance what each part of your money is for, then track spending against it. It imports bank files (and can connect to banks in many countries), syncs between your devices, and keeps your financial data on your own device or server instead of a company's cloud.

## Version and source
- Repository: https://github.com/actualbudget/actual
- Pinned commit: `27290a8990ef8c24c71c581f4da08d6df020a009`. Use exactly this version.
- Get it: `git clone https://github.com/actualbudget/actual actual-budget && cd actual-budget && git checkout 27290a8990ef8c24c71c581f4da08d6df020a009`
- Or download a zip: https://github.com/actualbudget/actual/archive/27290a8990ef8c24c71c581f4da08d6df020a009.zip
- Official docs: https://actualbudget.org/docs
- Licence: **MIT**. Free to use, change and share, even commercially. Keep the original copyright notice.

## Running it
- Easiest: docker run -d --name actual -p 5006:5006 -v actual-data:/data actualbudget/actual-server:latest # then open http://localhost:5006. Non-technical alternative: one-click PikaPods hosting (~$2/month).
- Needs: Docker, or a desktop download; Node 22 + Yarn 4 for development
- Develop: `yarn install && yarn start   # browser dev server; yarn start:server-dev to include the sync server`
- Test: `yarn test`
- Check/lint: `yarn typecheck && yarn lint:fix`
- Stack: typescript (React, Vite, Node.js, Electron, Yarn 4 workspaces). Difficulty for a non-developer with an AI: **moderate**. The core is a large TypeScript monorepo, but most personal adaptations use settings, custom themes, rules, or small scripts with the official @actual-app/api package. These need no fork.

## The project's own AI instructions
Read these in the repository before changing code: `AGENTS.md`, `CLAUDE.md`, `PRODUCT.md`, `DESIGN.md`, `CODE_REVIEW_GUIDELINES.md`.

## Customisation points (settings → extend → code)
- **currency-format-language** [settings]: Currency symbol, number and date formats, interface language. → `Settings → Currency, Format, Language`
- **budget-type** [settings]: Strict envelope budgeting or looser tracking. → `Settings → Budget type (envelope or tracking)`
- **rules-and-schedules** [settings]: Auto-categorise transactions, rename payees, and handle recurring bills. → `Rules and Schedules pages (rules support formulas and templates)`
- **custom-theme** [extend]: Your own colours via CSS variables, with no fork. → `Settings → Themes → Custom theme → Additional CSS overrides (docs/custom-themes.md; catalogue in packages/desktop-client/src/data/customThemeCatalog.json)`
- **api-scripts** [extend]: Small Node scripts that import bank CSVs, apply custom logic, export reports, or connect other tools. → `@actual-app/api npm package (packages/api, docs: actualbudget.org/docs/api)`
- **bank-sync** [settings]: Connect a supported bank provider for your country. → `Account → Link bank (packages/sync-server/src/app-*)`
- **core-ui** [code]: New screens or reports. Follow AGENTS.md (yarn commands from the root only). → `packages/desktop-client/src/components/** (UI), packages/loot-core/src/server/** (logic)`

## Must keep working
- Budget data and sync. Never change the data model, CRDT or sync code for a personal tweak.
- Encryption, authentication and server endpoints.
- Always run yarn commands from the repository root (see AGENTS.md).

## Staying updatable
Settings, rules, custom CSS themes and @actual-app/api scripts cover almost every personal adaptation without forking. Core changes are for agent-mode AIs only, and they need yarn typecheck, lint and tests to pass.

## Data, costs and safety
- Personal data: **yes**. Stored in: Budget files stored locally in the browser or desktop app; the sync server keeps an encrypted-capable copy in /data. Highly sensitive financial data. Turn on end-to-end encryption in settings, and make backups (Settings → Export) before trying changes.
- Service: Bank sync (GoCardless, SimpleFIN, Enable Banking, Pluggy, Akahu, depending on country) (optional, varies by provider and country (some free tiers)): Automatically import transactions from your bank.
- Service: Hosting (PikaPods or Fly.io) (optional, about $1.50–$2 per month): Run the sync server without managing a computer yourself.
- Turn on end-to-end encryption before syncing through a server you don't fully control.
- Bank-sync credentials and API passwords must never be pasted into an AI chat or committed to a repo.

---

# Customising Actual Budget

Actual is a big TypeScript monorepo, but **personal adaptations almost never need a fork**. Actual has strong settings, rules, custom themes, and an official API for scripts.

## Level 1: Settings (no code)
- **Currency, number/date format, language:** Settings.
- **Budget type:** envelope ("give every dollar a job") or tracking.
- **Categories and groups:** model the user's life, e.g. "Kids → Noa pocket money", "Holiday fund".
- **Rules:** automatically rename payees, set categories, split transactions. Rules support formulas/templates (`packages/loot-core/src/server/rules/`).
- **Schedules:** recurring bills and income.
- **Bank sync:** link a supported provider for the user's country (GoCardless, SimpleFIN, Enable Banking, Pluggy, Akahu).
- **Encryption:** turn on end-to-end encryption for synced budgets.

## Level 2: Extend (no fork)
### Custom theme (CSS)
Settings → Themes → **Custom theme** → *Additional CSS overrides*. Override the CSS variables (full guide in `packages/docs/docs/custom-themes.md`). Overrides persist across built-in themes.

### Scripts with `@actual-app/api`
`npm install @actual-app/api`. Docs: https://actualbudget.org/docs/api/ (source `packages/api/`). Typical scripts:
- Import a bank CSV that Actual's importer doesn't understand.
- Monthly summary email or a chat message.
- Sync with a spreadsheet.

Template:
```js
const api = require('@actual-app/api');
// dataDir must already exist (mkdir .actual-cache) and be in .gitignore
await api.init({ dataDir: './.actual-cache', serverURL: 'http://localhost:5006', password: process.env.ACTUAL_PASSWORD });
await api.downloadBudget(process.env.ACTUAL_SYNC_ID);
// ... api.getAccounts(), api.importTransactions(accountId, txns), api.getBudgetMonth('2026-10') ...
await api.shutdown();
```
Keep `ACTUAL_PASSWORD` and the budget sync ID in environment variables or a local `.env` that's in `.gitignore`. Never commit them.

## Level 3: Core code (agent mode only)
Follow upstream `AGENTS.md`:
- Run yarn from the **root** only.
- Run `yarn typecheck`, `yarn lint:fix` and `yarn test`.

| Change | Where |
|---|---|
| UI components, pages, reports | `packages/desktop-client/src/components/**` |
| Business logic | `packages/loot-core/src/server/**` |
| Shared components | `packages/component-library` |
| Sync server, bank providers | `packages/sync-server/src/**` |

Read `PRODUCT.md` and `DESIGN.md` for the product's tone ("calm, trustworthy, practical").

## Running locally
- **Just use it:** `docker run -d -p 5006:5006 -v actual-data:/data actualbudget/actual-server:latest`, then open http://localhost:5006. Desktop apps are at actualbudget.org/download.
- **Non-technical hosting:** PikaPods one-click (~$2/month).
- **Develop:** `yarn install && yarn start`.

## Pitfalls
- Financial data is sensitive. Make a backup (Settings → Export) before running new scripts.
- Test scripts against a **copy** of the budget first.
- Amounts in the API are integers in cents (e.g. 1234 = 12.34). Dates are `YYYY-MM-DD`.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/actual-budget/27290a8/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/actual-budget/27290a8/SKILL.md)