Connect your AI

What it does

Our Budget can share your budget with AI agents that run on your computer, like Claude Code and OpenAI Codex. Ask something like “How much did we spend on groceries last month?” and the agent reads the answer straight from your spaces: transactions, totals, categories, accounts and recurring expenses.

You need the Our Budget app and a Mac with Claude Code or Codex installed. On Linux or Windows, see other systems.

1. Create a key in the app

In Our Budget, open Settings → Connect your AI → Create key. Give it a name and choose how long it lasts: 30, 90 or 365 days.

The key is shown only once. Tap copy. With an iPhone and a Mac, Universal Clipboard makes it available on your Mac. Tap Done only after step 2: Done clears the clipboard.

2. Save the key in your Mac’s Keychain

Open Terminal and run:

security add-generic-password -U -T "" -s ourbudget-api -a "$USER" -w

When it asks for the password, paste the key and press Enter, then paste it again to confirm. Nothing appears while you paste; that’s normal.

From now on, macOS asks before anything reads the key. Choose Allow, not Always Allow, so every read stays under your control.

3. Add two commands to your shell

Add these lines to ~/.zshrc, then run source ~/.zshrc:

alias budget-claude='OURBUDGET_API_KEY="$(security find-generic-password -s ourbudget-api -w)" claude'
alias budget-codex='OURBUDGET_API_KEY="$(security find-generic-password -s ourbudget-api -w)" codex'

budget-claude and budget-codex load the key only into that session. Your other terminals and agent sessions never see it.

4. Give your agent the instructions

This downloads a short guide that tells the agent how to use the API safely. Claude Code reads CLAUDE.md and Codex reads AGENTS.md. It contains no key.

mkdir -p ~/budget
curl -fsSL https://ourbudget.co/ai-agent-instructions.md -o ~/budget/CLAUDE.md
cp ~/budget/CLAUDE.md ~/budget/AGENTS.md

View the instructions

5. Ask away

cd ~/budget && budget-claude    # or: cd ~/budget && budget-codex

Then try:

• How much did we spend by category last month?
• Compare our spending month by month this year.
• What were our biggest expenses in August?
• How much goes to needs versus wants?
• Which recurring bills are coming up?

Claude Code asks before it runs commands, and Codex asks before each request. Approve only requests to the Our Budget API (us-central1-expense-tracker-live.cloudfunctions.net).

Shared spaces

A space where you are the only member works right away. A shared space, for example one with your partner, can be read only after an owner or admin turns on Allow AI access in the space’s settings in the app. Every member can see that setting, because the agent reads everyone’s transactions in that space.

Keeping your data safe

• Access is read-only. Agents can’t change your budget.
• Keys are shown once and stored only as a one-way hash. Not even we can see them.
• Revoke a key in Settings → Connect your AI and it stops working immediately. Keys also expire, and changing your password or signing out everywhere revokes them.
• Never paste your key into a chat, a URL, or a file in a repository. If you think it leaked, revoke it and create a new one.
• Names and notes are written by people, including other members of shared spaces. Your agent is told to treat them as data, never as commands. Keep approvals on anyway.
• Each key has a daily usage limit.

Troubleshooting

• The agent says the key is missing: start it with budget-claude or budget-codex, and run source ~/.zshrc after adding the commands.
• 401 unauthorized or key_expired: create a new key in the app and repeat step 2. It replaces the old one.
• 403 ai_access_disabled: the space is shared. Ask an owner or admin to turn on Allow AI access in the space’s settings.
• 429 daily_limit_reached: the key used its daily limit. It resets at midnight UTC.
• macOS never asks for permission: the key was saved without -T "". Repeat step 2.

Other systems (Linux, Windows with WSL)

Keep the key in a file only you can read, outside any repository. Run this, paste the key and press Enter (nothing appears while you paste):

mkdir -p ~/.config/ourbudget
( umask 077 && read -rs KEY && printf '%s' "$KEY" > ~/.config/ourbudget/key )

Then use these commands instead of the ones in step 3:

alias budget-claude='OURBUDGET_API_KEY="$(cat ~/.config/ourbudget/key)" claude'
alias budget-codex='OURBUDGET_API_KEY="$(cat ~/.config/ourbudget/key)" codex'

For developers

The API answers GET requests only. Its self-describing guide needs no key: https://us-central1-expense-tracker-live.cloudfunctions.net/api/v1. Routes: /spaces, /spaces/{id}, /spaces/{id}/transactions, /spaces/{id}/summary and /spaces/{id}/recurring.

Questions? Write to hi@ourbudget.co.