Copilot Money

Get budgets from Copilot's native budget tracking. Returns the current-month effective budget per category plus the full `amounts` map of per-month overrides for history lookups. For parent categories, the returned `amount` is the resolved total (children + rollovers) that Copilot displays in the Budgets view. Totals use the current-month effective amount.

Get budgets from Copilot's native budget tracking (live, GraphQL-backed). Projects per-category budgets from the categories cache — the same fetch that powers get_categories_live populates this. Replaces get_budgets when --live-reads is on. Note: live mode does not include `name`, `period`, `start_date`, `end_date`, `is_active`, or `iso_currency_code` per budget — those fields aren't exposed on Copilot's GraphQL endpoint. Use cache-mode `get_budgets` if you need them. `amount` includes rollover; 0 can mean no budget (cleared and never set read the same); an excluded category has none.

Get information about the local data cache, including the date range of cached transactions and total count. Useful for understanding data availability before running historical queries. This tool reads from a local cache that may not contain your complete transaction history. Also reports decode_health: per-collection counts of documents dropped on schema validation failure (a "degraded" status means some cached documents are missing from results).

Unified category retrieval tool. Supports multiple views: list (default) - user categories with transaction counts/amounts for a time period; tree - user categories as hierarchical tree; search - search user categories by keyword. Use parent_id to get subcategories. For list view, use period (e.g., "this_month") or start_date/end_date to filter by date. Includes all categories, even those with $0 spent (matching UI behavior).

Get user categories (live, GraphQL-backed), including each category id, parentId, and a derived `budget_amount`. IMPORTANT: `budget_amount` is the BUDGETED amount for the month — NOT the amount spent. It includes rollover, so can exceed the amount set; 0 can mean no budget (cleared and never set read the same); null when the category has no budget object (e.g. excluded). To find actual spending in a category, call get_transactions_live with that category id and sum the transaction amounts; do not report the budget as spend. The budget data here is the same cache get_budgets_live reads from. Ea…

Get connection status for all linked financial institutions. Shows per-institution sync health including last successful update timestamps for transactions and investments, login requirements, and error states. Use this to check when accounts were last synced or to identify connections needing attention. Also reports decode_health: per-collection counts of cached documents dropped on schema validation failure (a "degraded" status means some documents are missing from results). Also reports scheduled_smoke: the last scheduled API-drift check with timestamp, or null if the weekly job is not inst…

Get monthly progress snapshots for financial goals. Returns current_amount, target_amount, daily data points, and contribution records per month. Filter by goal_id or month range (YYYY-MM). Cache-only: no live-mode (`--live-reads`) counterpart exists because Copilot's GraphQL endpoint does not expose goal data, so this tool always returns cached LevelDB data regardless of the `--live-reads` flag.

Get financial goals from Copilot's native goal tracking. Retrieves user-defined savings goals, debt payoff targets, and investment goals. Returns goal details including target amounts, monthly contributions, status (active/paused), start dates, and tracking configuration. Calculates total target amount across all goals. Cache-only: no live-mode (`--live-reads`) counterpart exists because Copilot's GraphQL endpoint does not expose goal data, so this tool always returns cached LevelDB data regardless of the `--live-reads` flag.

Get current investment holdings with position-level detail. Returns ticker, name, quantity, current price, equity value, average cost, and total return per holding. Joins data from account holdings, securities, and optionally historical snapshots. Filter by account or ticker symbol. Note: cost_basis may be unavailable for cash-equivalent positions. Positions on hidden and merged accounts are EXCLUDED by default, matching get_accounts — pass include_hidden: true for them. Do NOT sum holdings as portfolio value: unvested stock-plan shares are reported as holdings, so the sum can far exceed the i…

Get investment positions with cost-basis metrics (live, GraphQL-backed). One row per (account, security). For CASH sleeves and other positions where the server returns no cost-basis metrics, the four derived fields (cost_basis, average_cost, total_return, total_return_percent) are omitted from the row; check `is_cash_equivalent` (derived from `security.type === 'CASH'`) to distinguish. For monthly snapshots, use cache-mode `get_holdings` with `include_history: true` — history is not available on the live query. Positions on hidden and closed accounts are EXCLUDED by default, matching get_accou…

Get the portfolio asset-class allocation (live, GraphQL-backed). Returns one row per asset class — `type` (e.g. "EQUITY", "CASH", "FIXED_INCOME"), `amount` (dollar value), and `percentage` (share of total invested as a percent, 0–100). Optional `account_id` / `item_id` scope the allocation to a single account (applied server-side). Available when --live-reads is on.

Get your investments-only combined balance (live, GraphQL-backed): `current` (the current-moment combined investment-accounts balance — the "live dot") and `history` (a daily timeseries over the selected `time_frame`, ascending by date; each point is `{date, balance}` in dollars). Investments-only — distinct from get_networth_live (whole net worth) and get_balance_history_live (per-account). The history cache holds the most-recently-requested time_frame; requesting a different value refetches it. `history` is capped to the most recent `history_limit` points (default 30) — see that param to fet…

Get investment price history for portfolio tracking. Returns one row per (security, period) for stocks, ETFs, mutual funds, and crypto. Filter by ticker symbol, date range, or price type (daily/hf). By default each row is TERSE: the security, the period, and its latest price (`latest_price` / `latest_at`) — enough to answer "what is this worth". The full price series (`prices`, an epoch-millis map) is most of a full row and roughly quadruples response size, so it is omitted unless requested via `fields`; ask for it only when you need the time series itself, not a current value.

Get price history for a single security (live, GraphQL-backed). time_frame picks the query: ONE_DAY and ONE_WEEK return intraday timestamps (5-minute cache TTL); ONE_MONTH / THREE_MONTHS / YTD / ONE_YEAR / ALL return daily closes (1-hour TTL). The output `granularity` field says which row field to use (`date` daily, `timestamp` intraday). Server-side ownership gate: only securities you currently hold work — any other security_id returns a clean "not currently in your linked accounts" error; enumerate valid ids via get_holdings_live. Long ranges paginate via `max_rows` and `offset`; the respons…

Get stock split events from the local Firestore cache. Returns one row per (security, effective_date) with the adjustment multiplier (e.g. 0.1 for a 10-for-1 split — multiply pre-split prices/quantities by this value to convert to the post-split equivalent). Joined with the securities collection so each row includes ticker and name. IMPORTANT: prices returned by `get_investment_prices` and `get_investment_prices_live` are ALREADY split-adjusted by Copilot. Use this tool only when you need the split events themselves (e.g., for narrative or historical-analysis purposes) — you do NOT need to app…

Current month's NON-RECURRING spend, day by day (live). `total_amount` is CUMULATIVE month-to-date; `daily_amount` is that day's increase (the first row's, its own total). Counts REGULAR transactions with no recurring link, net of refunds, pending included; leaves out income, transfers, recurring charges (rent, subscriptions) and UNCATEGORIZED rows, so it is NOT the app's "spent this month" — for that, follow the spend recipe in get_transactions_live's description. On the latest row, `comparison_amount` matched the Dashboard's "$N under" budget figure (one measurement, #844); it is not a "vs l…

Get net-worth-over-time history (live, GraphQL-backed). Returns daily snapshots sorted oldest→newest by date; for each row, `assets - debt` gives the net worth at that point in time. Both `assets` and `debt` are nullable numbers — early dates in the user's history may have `assets: null` until backfilled. Available when --live-reads is on. Optional `time_frame` arg (default "YTD"; accepts the canonical TimeFrame values "ONE_DAY", "ONE_WEEK", "ONE_MONTH", "THREE_MONTHS", "YTD", "ONE_YEAR", "ALL"). The cache holds the most-recently-requested time_frame; requesting a different value triggers a fr…

Get user-confirmed recurring/subscription items (live, GraphQL-backed). Replaces get_recurring_transactions when --live-reads is on. NOTE: pattern-based detection from transactions is NOT included — only Copilot's native subscription tracking. Run without --live-reads if you need pattern detection. Each row carries a `category_name` resolved from the categories list (loaded on first use); `null` when the row has no category or its category was deleted, and on every row if the categories read fails, which `_category_warning` then reports. Default rows are terse: id, name, state, frequency, next…

Identify recurring/subscription charges. Combines two data sources: (1) Pattern analysis - finds transactions from same merchant with similar amounts, returns estimated frequency, confidence score, and next expected date. (2) Copilot's native subscription tracking - returns user-confirmed subscriptions stored in the app. Both sources are included by default for comprehensive coverage. Rows in the pattern-analysis `recurring` array are terse by default: merchant, normalized_merchant, occurrences, average_amount, total_amount, frequency, confidence, category_name, last_date, next_expected_date. …

Get all user tags (live, GraphQL-backed). Each row carries `id`, `name`, and `color`. No cache-mode counterpart exists — this tool is the only way to enumerate tags. Use this to enumerate tag IDs before calling `get_transactions_live` with a tag filter, or to enrich transaction-tag references with human-readable names. Available when --live-reads is on.

Get the biggest movers across your investment holdings (live, GraphQL-backed). One row per security with an aggregate `change` (the ranked metric in the requested filter's units — dollars for MY_EQUITY_CHANGE, raw security price change for PRICE_CHANGE). Default rows are terse (security_id, ticker_symbol, name, type, change) — the intraday `price_points` series (`{timestamp, price}`; `timestamp` is epoch milliseconds) is opt-in via `fields`. The `filter` selects the ranking basis: "MY_EQUITY_CHANGE" (default — dollar impact on your position, price change weighted by held quantity) or "PRICE_CH…

Description is built at runtime.

Description is built at runtime.

Get the next-due recurring/subscription items — the "about to bill" view (live, GraphQL-backed). Returns unpaid upcoming payments sorted by due date (soonest first). HORIZON (unverified, #844, parity row REC-07): one read returned only rows due within about 14 days, with most configured recurrings absent, so do not treat this as "every bill left this month"; for bills due later, use get_recurring_live's nextPaymentDate. DISTINCT from `get_recurring_live`, which returns the full set of configured/historical recurrings; use this tool when the user asks "what's coming up" or "what bills am I abou…

Flush the in-memory live cache by scope. Use when the user explicitly wants fresh data despite TTLs. Does not touch LevelDB (use refresh_database for that). Live-reads mode only.

Refresh the in-memory cache by reloading data from the local Copilot Money database. Use this when the user has recently synced new transactions in the Copilot Money app, or when you suspect the cached data is stale. The cache also auto-refreshes every 5 minutes. Returns the updated cache info after refresh.

Bulk mark transactions as reviewed (or unreviewed). Pass `transaction_ids` (resolved locally — works only within the resolution window) OR `rows` — an array of {transaction_id, account_id, item_id} from a live read that works for ANY transactions, including out-of-window backlog; prefer `rows` for large sweeps. One of the two is required; `rows` wins when both are given. The whole set is applied in ONE GraphQL request. If the server rejects or silently skips any row the call throws, naming the affected ids; `reviewed_count` reflects what actually landed.

Set the monthly budget amount for a category. amount="0" clears the budget. Pass month="YYYY-MM" for a single-month override; omit for the all-months default. Note: if the user has disabled "Enable budgeting" or "Enable rollover" in Copilot → Settings → General, the budget write still succeeds on the server, but the value will not appear in the Copilot UI until those toggles are re-enabled. Rollover behavior also depends on the "Rollover categories" selection in the same settings pane, which is not writable through this tool. On an excluded category the write succeeds but reads hide the budget…

Change the state of a recurring item (subscription/charge). Set to ACTIVE, PAUSED, or ARCHIVED (uppercase, matching the GraphQL API). Requires recurring_id (from get_recurring_transactions). Writes directly to Copilot Money via GraphQL.

Split one parent transaction into 2+ child transactions (e.g. a 'Hotel + Car + Meals' charge into three per-category children). Requires the parent transaction_id, account_id, and item_id plus `splits` (min 2 entries; each needs `amount` and `category_id`; `name`/`date` default to the parent's). Child amounts must sum to the parent's amount — validated client-side and server-enforced. If the parent cannot be resolved locally (outside the resolution window), the split still proceeds when every entry carries explicit `name` and `date`; the sum check then defers to the server. On success the pare…

Update an existing user-defined category. Provide category_id (required) and any fields to change: name, emoji, color_name, or is_excluded. Only the specified fields are updated. Note: parent/child category hierarchies are not writable through Copilot's GraphQL API. Writes directly to Copilot Money via GraphQL.

Update an existing recurring transaction. Pass recurring_id plus at least one of name, category_id, frequency, state, or rule. Writes directly to Copilot Money via GraphQL.

Update an existing tag. Provide tag_id (required) and at least one of name or color_name. Only the specified fields are updated. Writes directly to Copilot Money via GraphQL.

Update a single transaction. Pass transaction_id plus at least one of name, category_id, note, tag_ids, type, reviewed, date, or amount — only the fields you pass change. note="" clears the note; tag_ids=[] clears all tags. category_id cannot be combined with type INCOME or INTERNAL_TRANSFER (those clear the category server-side) — pass the type alone, or REGULAR to keep/set a category. amount/date/type edits of a known split parent (or when unchecked) are refused. If the transaction cannot be resolved locally (outside the resolution window), also pass account_id and item_id from a live read. …

Apply many DIFFERENT transaction edits in ONE call — the per-row bulk form of update_transaction. Use it when rows need different values, or the edit touches name, note, date, or amount (Copilot cannot bulk-edit those four); for one IDENTICAL change to category/type/reviewed or a tag add/remove, prefer bulk_edit_transactions (ONE request instead of N). WARNING: an entry's tag_ids REPLACES that row's whole tag list, silently dropping existing tags — to add/remove a tag while keeping the rest, use bulk_edit_transactions add_tag_ids/remove_tag_ids. Entries are independent and take update_transact…