{"owner":"actualbudget","repo":"actual","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md"],"files":{"AGENTS.md":"# AGENTS.md - Guide for AI Agents Working with Actual Budget\n\nThis guide provides comprehensive information for AI agents (like Cursor) working with the Actual Budget codebase.\n\n## Project Overview\n\n**Actual Budget** is a local-first personal finance tool written in TypeScript/JavaScript. It's 100% free and open-source with synchronization capabilities across devices.\n\n- **Repository**: https://github.com/actualbudget/actual\n- **Community Docs**: Documentation is part of the monorepo at `packages/docs/`. Published at https://actualbudget.org/docs\n- **License**: MIT\n- **Primary Language**: TypeScript (with React)\n- **Build System**: Yarn 4 workspaces (monorepo)\n\n## Quick Start Commands\n\n### Essential Commands (Run from Root)\n\n```bash\n# Type checking (ALWAYS run before committing)\nyarn typecheck\n\n# Linting and formatting (with auto-fix)\nyarn lint:fix\n\n# Run all tests\nyarn test\n\n# Start development server (browser)\nyarn start\n\n# Start with sync server\nyarn start:server-dev\n\n# Start desktop app development\nyarn start:desktop\n```\n\n### Important Rules\n\n- **ALWAYS run yarn commands from the root directory** - never run them in child workspaces\n- Use `yarn workspace <workspace-name> run <command>` for workspace-specific tasks\n- Tests run once and exit by default (using `vitest --run`)\n\n### ⚠️ PR titles must start with `[AI]`\n\nEvery pull request title must be prefixed with `[AI]` — you have to apply it\nyourself. See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md).\n\n### Task Orchestration with Lage\n\nThe project uses **[lage](https://microsoft.github.io/lage/)** (a task runner for JavaScript monorepos) to efficiently run tests and other tasks across multiple workspaces:\n\n- **Parallel execution**: Runs tests in parallel across workspaces for faster feedback\n- **Smart caching**: Caches test results to skip unchanged packages (cached in `.lage/` directory)\n- **Dependency awareness**: Understands workspace dependencies and execution order\n- **Continues on error**: Uses `--continue` flag to run all packages even if one fails\n\n**Lage Commands:**\n\n```bash\n# Run all tests across all packages\nyarn test                    # Equivalent to: lage test --continue\n\n# Run tests without cache (for debugging/CI)\nyarn test:debug              # Equivalent to: lage test --no-cache --continue\n```\n\nConfiguration is in `lage.config.js` at the project root.\n\n## Architecture & Package Structure\n\n### Core Packages\n\n#### 1. **loot-core** (`packages/loot-core/`)\n\nThe core application logic that runs on any platform.\n\n- Business logic, database operations, and calculations\n- Platform-agnostic code\n- Exports for both browser and node environments\n- Test commands:\n\n  ```bash\n  # Run all loot-core tests\n  yarn workspace @actual-app/core run test\n\n  # Or run tests across all packages using lage\n  yarn test\n  ```\n\n#### 2. **desktop-client** (`packages/desktop-client/` - aliased as `@actual-app/web`)\n\nThe React-based UI for web and desktop.\n\n- React components using functional programming patterns\n- E2E tests using Playwright\n- Vite for bundling\n- Commands:\n\n  ```bash\n  # Development\n  yarn workspace @actual-app/web start:browser\n\n  # Build\n  yarn workspace @actual-app/web build\n\n  # E2E tests\n  yarn workspace @actual-app/web e2e\n\n  # Visual regression tests\n  yarn workspace @actual-app/web vrt\n  ```\n\n#### 3. **desktop-electron** (`packages/desktop-electron/`)\n\nElectron wrapper for the desktop application.\n\n- Window management and native OS integration\n- E2E tests for Electron-specific features\n\n#### 4. **api** (`packages/api/` - aliased as `@actual-app/api`)\n\nPublic API for programmatic access to Actual.\n\n- Node.js API\n- Designed for integrations and automation\n- Commands:\n\n  ```bash\n  # Build\n  yarn workspace @actual-app/api build\n\n  # Run tests\n  yarn workspace @actual-app/api test\n\n  # Or use lage to run all tests\n  yarn test\n  ```\n\n#### 5. **sync-server** (`packages/sync-server/` - aliased as `@actual-app/sync-server`)\n\nSynchronization server for multi-device support.\n\n- Express-based server\n- Currently transitioning to TypeScript (mostly JavaScript)\n- Commands:\n  ```bash\n  yarn workspace @actual-app/sync-server start\n  ```\n\n#### 6. **component-library** (`packages/component-library/` - aliased as `@actual-app/components`)\n\nReusable React UI components.\n\n- Shared components like Button, Input, Menu, etc.\n- Theme system and design tokens\n- Icons (375+ icons in SVG/TSX format)\n\n#### 7. **crdt** (`packages/crdt/` - aliased as `@actual-app/crdt`)\n\nCRDT (Conflict-free Replicated Data Type) implementation for data synchronization.\n\n- Protocol buffers for serialization\n- Core sync logic\n\n#### 8. **plugins-service** (`packages/plugins-service/`)\n\nService for handling plugins/extensions.\n\n#### 9. **eslint-plugin-actual** (`packages/eslint-plugin-actual/`)\n\nCustom ESLint rules specific to Actual.\n\n- `no-untranslated-strings`: Enforces i18n usage\n- `prefer-trans-over-t`: Prefers Trans component over t() function\n- `prefer-logger-over-console`: Enforces using logger instead of console in `packages/loot-core/`\n- `typography`: Typography rules\n- `prefer-if-statement`: Prefers explicit if statements\n\n#### 10. **docs** (`packages/docs/`)\n\nDocumentation website built with Docusaurus.\n\n- Documentation is part of the monorepo\n- Built with Docusaurus 3\n- Commands:\n  ```bash\n  yarn workspace docs start\n  yarn workspace docs build\n  yarn start:docs  # From root\n  ```\n\n## Development Workflow\n\n### 1. Making Changes\n\nWhen implementing changes:\n\n1. Read relevant files to understand current implementation\n2. Make focused, incremental changes\n\n### 2. Testing Strategy\n\n**Unit Tests (Vitest)**\n\nThe project uses **lage** for running tests across all workspaces efficiently.\n\n```bash\n# Run all tests across all packages (using lage)\nyarn test\n\n# Run tests without cache (for debugging)\nyarn test:debug\n\n# Run tests for a specific package\nyarn workspace @actual-app/core run test\n```\n\n**E2E Tests (Playwright)**\n\n```bash\n# Run E2E tests for web\nyarn e2e\n\n# Desktop Electron E2E (includes full build)\nyarn e2e:desktop\n\n# Visual regression tests\nyarn vrt\n\n# Visual regression in Docker (consistent environment)\nyarn vrt:docker\n\n# Run E2E tests for a specific package\nyarn workspace @actual-app/web e2e\n```\n\n**Testing Best Practices:**\n\n- Minimize mocked dependencies - prefer real implementations\n- Use descriptive test names\n- Vitest globals are available: `describe`, `it`, `expect`, `beforeEach`, etc.\n- For sync-server tests, globals are explicitly defined in config\n\n### 3. Type Checking\n\nTypeScript configuration uses:\n\n- Incremental compilation\n- Strict type checking with `typescript-strict-plugin`. New files must be\n  type-strict — don't add `// @ts-strict-ignore` to a new file (existing files\n  are grandfathered).\n- Platform-specific exports in `loot-core` (node vs browser)\n\n### 4. Internationalization (i18n)\n\nUse the `Trans` component (and translated strings) for user-facing text.\nRegenerate i18n files with `yarn generate:i18n`.\n\n### 5. Financial Number Typography\n\nWrap standalone financial numbers with `FinancialText` (or `styles.tnum` where\nwrapping isn't possible).\n\n## Code Style & Conventions\n\n### TypeScript Guidelines\n\n**Type Usage:**\n\n- Use TypeScript for all code; look for existing type definitions before adding new ones\n- Prefer `satisfies` over type assertions (`as`, `!`) for narrowing\n\n**Naming:**\n\n- Use descriptive variable names with auxiliary verbs (e.g., `isLoaded`, `hasError`)\n\n**Code Structure:**\n\n- Functional and declarative programming patterns - avoid classes\n- Use the `function` keyword for pure functions\n- Prefer iteration and modularization over code duplication\n- Structure files: exported component/page, helpers, static content, types\n- Create new components in their own files\n\n**React Patterns:**\n\n- The project uses **React Compiler** (`babel-plugin-react-compiler`) in all app packages with React code (desktop-client, component-library). The compiler auto-memoizes component bodies, so you can omit manual `useCallback`, `useMemo`, and `React.memo` when adding or refactoring code; prefer inline callbacks and values unless a stable identity is required by a non-compiled dependency.\n- Avoid unstable nested components\n\n**JSX Style:**\n\n- Declarative JSX, minimal and readable\n- Avoid unnecessary curly braces in conditionals\n- Use concise syntax for simple statements\n- Prefer explicit expressions (`condition && <Component />`)\n\n### Platform-Specific Code\n\n- Use conditional exports in `loot-core` for platform-specific code; platform\n  resolution happens at build time via package.json exports. Don't directly\n  import another platform's modules (`.api`, `.electron`).\n\nFor commit and PR rules, see\n[PR and Commit Rules](.github/agents/pr-and-commit-rules.md).\n\n## File Structure Patterns\n\n### Typical Component File\n\n```typescript\nimport { type ComponentType } from 'react';\n// ... other imports\n\ntype MyComponentProps = {\n  // Props definition\n};\n\nexport function MyComponent({ prop1, prop2 }: MyComponentProps) {\n  // Component logic\n  return (\n    // JSX\n  );\n}\n```\n\n### Test File\n\n```typescript\nimport { describe, it, expect, beforeEach } from 'vitest';\n// ... imports\n\ndescribe('ComponentName', () => {\n  it('should behave as expected', () => {\n    // Test logic\n    expect(result).toBe(expected);\n  });\n});\n```\n\n## Important Directories & Files\n\n### Configuration Files\n\n- `/package.json` - Root workspace configuration, scripts\n- `/lage.config.js` - Lage task runner configuration\n- `/.oxlintrc.json` - Lint rules (oxlint); `/.oxfmtrc.json` - formatting (oxfmt)\n- `/.nano-staged.json` - pre-commit format/lint config (run via Husky)\n- `/.claude/settings.json`, `/.codex/config.toml`, `/.cursor/hooks.json` - agent\n  hook wiring; shared scripts live in `/scripts/agent-hooks/` and require `jq`\n  on PATH (a missing `jq` fails the hooks with an install message)\n- `/.agents/skills/` - symlink mirror of `/.claude/skills/` so Codex-based\n  harnesses (Codex CLI, IDE extension, ChatGPT desktop app) discover the same\n  skills; when adding a skill, create it in `/.claude/skills/` and add a\n  matching relative symlink here\n- `/tsconfig.json` - Root TypeScript configuration\n- `/.cursorignore`, `/.gitignore` - Ignored files\n- `/yarn.lock` - Dependency lockfile (Yarn 4)\n\n### Documentation\n\n- `/README.md` - Project overview\n- `/CONTRIBUTING.md` - Points to community docs\n- `/upcoming-release-notes/` - Release notes for next version. Name each file\n  with a short, descriptive slug (e.g. `add-payee-autocomplete.md`) — the PR link\n  is resolved automatically at release time, so you don't need the PR number.\n  Numeric filenames like `1234.md` also remain valid. See the release-note\n  template and rules in `packages/docs/docs/contributing/index.md`.\n- `/CODEOWNERS` - Code ownership definitions\n- `/packages/docs/` - Documentation website (Docusaurus)\n\n### Build Artifacts (Don't Edit)\n\n- `packages/*/lib-dist/` - Built output\n- `packages/*/dist/` - Built output\n- `packages/*/build/` - Built output\n- `packages/desktop-client/playwright-report/` - Test reports\n- `packages/desktop-client/test-results/` - Test results\n- `.lage/` - Lage task runner cache (improves test performance)\n\n### Key Source Directories\n\n- `packages/loot-core/src/client/` - Client-side core logic\n- `packages/loot-core/src/server/` - Server-side core logic\n- `packages/loot-core/src/shared/` - Shared utilities\n- `packages/loot-core/src/types/` - Type definitions\n- `packages/desktop-client/src/components/` - React components\n- `packages/desktop-client/src/hooks/` - Custom React hooks\n- `packages/desktop-client/e2e/` - End-to-end tests\n- `packages/component-library/src/` - Reusable components\n- `packages/component-library/src/icons/` - Icon components (auto-generated, don't edit)\n- `packages/docs/docs/` - Documentation source files (Markdown)\n- `packages/docs/docs/contributing/` - Developer documentation\n\n## Common Development Tasks\n\n### Running Specific Tests\n\n```bash\n# Run all tests across all packages (recommended)\nyarn test\n\n# E2E test for a specific file\nyarn workspace @actual-app/web run playwright test accounts.test.ts --browser=chromium\n```\n\n### Building for Production\n\n```bash\n# Browser build\nyarn build:browser\n\n# Desktop build\nyarn build:desktop\n\n# API build\nyarn build:api\n\n# Sync server build\nyarn build:server\n```\n\n### Type Checking Specific Packages\n\nTypeScript uses project references. Run `yarn typecheck` from root to check all packages.\n\n### Debugging Tests\n\n```bash\n# Run tests in debug mode (without parallelization)\nyarn test:debug\n\n# Run specific E2E test with headed browser\nyarn workspace @actual-app/web run playwright test --headed --debug accounts.test.ts\n```\n\n### Working with Icons\n\nIcons in `packages/component-library/src/icons/` are auto-generated. Don't manually edit them.\n\n## Troubleshooting\n\n### Type Errors\n\n1. Run `yarn typecheck` to see all type errors\n2. Check if types are imported correctly\n3. Look for existing type definitions in `packages/loot-core/src/types/`\n4. Use `satisfies` instead of `as` for type narrowing\n\n### Linter Errors\n\nRun `yarn lint` to check. All rules — including the custom `actual/*` rules\n(`no-untranslated-strings`, `prefer-trans-over-t`, `prefer-logger-over-console`,\n`typography`, …) — are defined in [`.oxlintrc.json`](.oxlintrc.json).\n\n### Test Failures\n\n1. Check if test is running in correct environment (node vs web)\n2. For Vitest: check `vitest.config.ts` or `vitest.web.config.ts`\n3. For Playwright: check `playwright.config.ts`\n4. Ensure mock minimization - prefer real implementations\n5. **Lage cache issues**: Clear cache with `rm -rf .lage` if tests behave unexpectedly\n6. **Tests continue on error**: With `--continue` flag, all packages run even if one fails\n\n### Import Resolution Issues\n\n1. Check `tsconfig.json` for path mappings\n2. Check package.json `exports` field (especially for loot-core)\n3. Verify platform-specific imports (`.electron`, `.api`)\n4. Use absolute imports in `desktop-client`\n\n### Build Failures\n\n1. Clean build artifacts: `rm -rf packages/*/dist packages/*/lib-dist packages/*/build`\n2. Reinstall dependencies: `yarn install`\n3. Check Node.js version (requires >=22)\n4. Check Yarn version (requires ^4.9.1)\n\n## Testing Patterns\n\n### Unit Tests\n\n- Located alongside source files or in `__tests__` directories\n- Use `.test.ts`, `.test.tsx`, `.spec.js` extensions\n- Vitest is the test runner\n- Minimize mocking - prefer real implementations\n\n### E2E Tests\n\n- Located in `packages/desktop-client/e2e/`\n- Use Playwright test runner\n- Visual regression snapshots in `*-snapshots/` directories\n- Page models in `e2e/page-models/` for reusable page interactions\n- Mobile tests have `.mobile.test.ts` suffix\n\n### Visual Regression Tests (VRT)\n\n- Snapshots stored per test file in `*-snapshots/` directories\n- Use Docker for consistent environment: `yarn vrt:docker`\n\n## Additional Resources\n\n- **Community Documentation**: https://actualbudget.org/docs/contributing/\n- **Discord Community**: https://discord.gg/pRYNYr4W5A\n- **GitHub Issues**: https://github.com/actualbudget/actual/issues\n- **Feature Requests**: Label \"needs votes\" sorted by reactions\n\n## Code Quality Checklist\n\nBefore committing changes, ensure:\n\n- [ ] Commit and PR rules followed (see [PR and Commit Rules](.github/agents/pr-and-commit-rules.md))\n- [ ] Platform-specific code uses proper exports\n\n## Pull Request Guidelines\n\nSee [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for complete PR creation rules, including title prefix requirements, labeling, the GitHub comment/review/issue 🤖 prefix, and PR template handling.\n\n## Code Review Guidelines\n\nWhen performing code reviews (especially for LLM agents): **see [CODE_REVIEW_GUIDELINES.md](./CODE_REVIEW_GUIDELINES.md)** for specific guidelines.\n\n## Performance Considerations\n\n- **Bundle Size**: Check with rollup-plugin-visualizer\n- **Type Checking**: Uses incremental compilation\n- **Testing**: Tests run in parallel by default\n- **Linting**: ESLint caches results for faster subsequent runs\n\n## Workspace Commands Reference\n\n```bash\n# List all workspaces\nyarn workspaces list\n\n# Run command in specific workspace\nyarn workspace <workspace-name> run <command>\n\n# Run command in all workspaces\nyarn workspaces foreach --all run <command>\n\n# Install production dependencies only (for server deployment)\nyarn install:server\n```\n\n## Environment Requirements\n\n- **Node.js**: >=22\n- **Yarn**: ^4.9.1 (managed by packageManager field)\n- **Browser Targets**: Electron >= 35.0, modern browsers (see browserslist)\n\n## Migration Notes\n\nThe codebase is actively being migrated:\n\n- **JavaScript → TypeScript**: sync-server is in progress\n- **Classes → Functions**: Prefer functional patterns\n- **React.\\* → Named Imports**: Legacy React.\\* patterns being removed\n\nWhen working with older code, follow the newer patterns described in this guide.\n\n## Cursor Cloud specific instructions\n\n### Services overview\n\n| Service             | Command                 | Port | Required                      |\n| ------------------- | ----------------------- | ---- | ----------------------------- |\n| Web Frontend (Vite) | `yarn start`            | 3001 | Yes                           |\n| Sync Server         | `yarn start:server-dev` | 5006 | Optional (sync features only) |\n\nAll storage is **SQLite** (file-based via `better-sqlite3`). No external databases or services are needed.\n\n### Running the app\n\n- `yarn start` builds the plugins-service worker, loot-core browser backend, and starts the Vite dev server on port **3001**.\n- `yarn start:server-dev` starts both the sync server (port 5006) and the web frontend together.\n- The Vite HMR dev server serves many unbundled modules. In constrained environments, the browser may hit `ERR_INSUFFICIENT_RESOURCES`. If that happens, use `yarn build:browser` followed by serving the built output from `packages/desktop-client/build/` with proper COOP/COEP headers (`Cross-Origin-Opener-Policy: same-origin`, `Cross-Origin-Embedder-Policy: require-corp`).\n\n### Lint, test, typecheck\n\nStandard commands documented in `package.json` scripts and the Quick Start section above:\n\n- `yarn lint` / `yarn lint:fix` (uses oxlint + oxfmt)\n- `yarn test` (lage across all workspaces)\n- `yarn typecheck` (tsgo + lage typecheck)\n\n### Testing and previewing the app\n\nWhen running the app for manual testing or demos, use **\"View demo\"** on the initial setup screen (after selecting \"Don't use a server\"). This creates a test budget pre-populated with realistic sample data (accounts, transactions, categories, and budgeted amounts), which is far more useful than starting with an empty budget.\n\n### Gotchas\n\n- The `engines` field requires **Node.js >=22** and **Yarn ^4.9.1**. The `.nvmrc` specifies `v24.18.1`.\n- Pre-commit hook runs `nano-staged` (oxfmt + oxlint, configured in `.nano-staged.json`) via Husky. Run `yarn prepare` once after install to set up hooks.\n- Lage caches test results in `.lage/`. If tests behave unexpectedly, clear with `rm -rf .lage`.\n- Native modules (`better-sqlite3`, `bcrypt`) require build tools (`gcc`, `make`, `python3`). These are pre-installed in the Cloud VM.\n- All yarn commands must be run from the repository root, never from child workspaces.\n","CLAUDE.md":"@AGENTS.md\n@.github/agents/pr-and-commit-rules.md\n"}}