# Use with AI agents

AI coding agents such as Claude Code, Cursor or Codex can already run terminal commands, so they can drive fob-actual directly. Ask in plain language, for example "how much did we spend on groceries each month this year?", and the agent runs the commands, reads the JSON and answers.

<Video title="Ask your budget questions with Claude Code and fob-actual (3–4 min)" />

## 1. Install and connect

Install the CLI and connect your budget yourself first ([install](/docs/actual/cli/install), [connect](/docs/actual/connect)), so the agent never needs your password. Check with `fob-actual auth status`.

<Callout type="warning" title="Decide what the agent may change">
A session token that can read your budget can also change it. Keep your agent's approval prompts on for any command that writes, and ask it to use `--dry-run` first. For a sandbox, export your budget from Actual, import it as a second budget, and point a separate profile at that one.
</Callout>

## 2. Tell the agent about fob-actual

Add a short note to your project's agent instructions (`CLAUDE.md`, `AGENTS.md`, `.cursorrules` or similar):

```markdown
## Budget (Actual)

Use the `fob-actual` CLI for anything about our budget.

- Start with `fob-actual auth status` to confirm which budget is bound.
- Discover commands with `fob-actual --help` and `fob-actual <resource> <action> --help`.
- Use `--json` and parse it. Amounts in JSON are integer minor units: divide by 100.
- For questions across accounts, use `fob-actual query run` (ActualQL).
- Run every write with `--dry-run` first and show me the result. Never pass `--yes` without asking me.
- Docs (raw Markdown): https://finopsbricks.com/llms.txt
```

## 3. Ask

Some requests that work well:

- "What did we spend per category last month, compared with what we budgeted?"
- "Which payees look like duplicates? Show me before merging anything."
- "Import the transactions in `september.csv` into Checking." The agent converts the CSV to the JSON format, runs `transactions import --dry-run`, and shows you what would be added.
- "Find uncategorized transactions and suggest a category for each."

## Docs for agents

Every docs page is also served as raw Markdown, which is easier for agents to read than HTML:

- Index of all pages: [`/llms.txt`](/llms.txt)
- Any page: add `/md` after `/docs`. For example, this page is at [`/docs/md/actual/cli/ai-agents`](/docs/md/actual/cli/ai-agents)