# Project pack: Actual Budget @ 27290a8

Facts about **Actual Budget** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.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.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- 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 the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/actualbudget/actual bespoke-actual-budget
  cd bespoke-actual-budget
  git checkout --detach 27290a8990ef8c24c71c581f4da08d6df020a009
  # Prepare development requirements and local configuration first.
  # Setup notes: browser dev server; yarn start:server-dev to include the sync server
  yarn install && yarn start
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  docker run -d --name actual -p 5006:5006 -v actual-data:/data actualbudget/actual-server:latest # then open http://localhost:5006. Hosted options: PikaPods (simpler, about US$2/month) or Fly.io (usage-based pricing).
  ```

- 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, PikaPods about US$2/month; Fly.io usage-based pricing; check current prices before choosing): 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 coin 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 and hosting
Clarify the person's goal and needs first, then discuss hosting if it has not already been chosen. Use their currency and locale for budget settings and examples.

A temporary AI sandbox can edit and test, but cannot host Actual long term. The app still needs the person's computer, PikaPods or Fly.io for day-to-day use.

- **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.
- **Hosted options:** PikaPods (simpler, one-click managed hosting, about US$2/month) or Fly.io (requires configuring deployment, usage-based pricing). Check current prices and get consent before starting a paid service.
- **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/r3/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/actual-budget/27290a8/r3/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/actual-budget/27290a8/r3/SKILL.md)