AI Reporting with Claude Code
Overview
@ultracart/bq-skill is a command-line tool that builds reports against your UltraCart
Data Warehouse (BigQuery). It installs a command called uc-bq plus a skill
prompt for Claude Code, Anthropic's terminal coding agent.
The split of work matters more than any single feature. Claude Code does the thinking: it reads
your BigQuery schema, writes the SQL, designs the chart, and saves a manifest describing how to
rebuild the report. The uc-bq CLI does the execution, and it does that part in plain Node.js.
Once a report exists you can refresh it forever without Claude Code, without an API key, and
without paying for a single AI token.
That is the whole idea behind the phrase "reports as code". A report is not a saved view inside
somebody else's dashboard product. It is a directory of SQL, JavaScript, and YAML sitting in
your Git repository, reviewable in a pull request and revertable with git revert.
The package is published on npm as
@ultracart/bq-skill under the Apache-2.0
licence, and the source is on
GitHub.
How a report moves from question to schedule
The design pass on the left happens once, in conversation. Everything from uc-bq run rightward
is deterministic and repeatable, which is what makes the tool safe to put on a schedule.
What a report actually is
Every report is a self-contained directory under ./reports/{merchant_id}/{report-name}/. The
files split cleanly into two groups: the ones you commit, and the ones the CLI regenerates on
every run.
| File | Committed | Purpose |
|---|---|---|
report.yaml | yes | The manifest. Parameters, chart type, alarms, delivery, run history. |
query.sql | yes | Parameterized SQL, using BigQuery named parameters. |
chart.js | yes | A formatChartData(data, isDashboard) function returning an ECharts option object. |
analysis_prompt.md | yes | The system prompt used to generate executive analysis on later runs. |
data.json | no | Query results from the most recent run. |
chart.png | no | The rendered chart. |
chart-dashboard.png | no | A 200x200 thumbnail for dashboard tiles. |
report.md | no | The generated executive analysis. |
report.pdf | no | Chart and analysis combined into one document. |
alarm_state.json | no | Metric history and active alarm suppressions. |
Because the committed half is text, two people can review a change to a revenue definition the same way they review a change to application code.
Where this fits alongside UltraCart's other reporting
UltraCart offers several routes to the same data warehouse, and they are meant for different jobs rather than competing.
| You want to | Use |
|---|---|
| Ask a one-off question in the browser, without SQL | AI-Powered Report Builder |
| Share a saved report with staff inside UltraCart | AI-Powered Report Viewer |
| Assemble in-app tiles into a dashboard | AI-Powered Report Dashboards |
| Keep reports in Git, review them in pull requests, and schedule them in CI | This section |
| Pull warehouse data into a spreadsheet | Data Warehouse (BigQuery) to Google Sheets |
| Query the warehouse directly from Looker Studio or Power BI | Data Warehouse (BigQuery) |
The in-app builder is the faster path to an answer. uc-bq is the path to an answer that keeps
arriving every Monday morning without anyone opening a browser.
The two work well in sequence. Prototype the question in the AI-Powered Report Builder, then ask Claude Code to turn the validated logic into a committed report you can schedule.
What it costs
There are three separate cost lines, and two of them are usually zero.
BigQuery query cost is billed by Google at on-demand rates, currently $6.25 per TB scanned.
Every uc-bq command that runs a query performs a dry run first and aborts if the estimate
exceeds a safety limit, which defaults to 10 GB, roughly $0.06 per query. See
Cost protection.
LLM cost applies only when a run generates executive analysis. Replays started with
--no-analysis, or with no API key present, make no model calls at all.
Claude Code cost applies while you are designing or refining a report, and stops when the conversation does.
UltraCart covers the first $1.00 of BigQuery expense on the project each month, which is enough to cover storage and the streaming updates. See Pricing for how warehouse billing works.
What is in this section
| Page | Covers |
|---|---|
| Getting started | Prerequisites, install, Google Cloud authentication, first report |
| Building reports with Claude Code | The conversational design loop, refining a report, chart types |
| CLI reference | Every command, subcommand, and flag |
| Configuration reference | .ultracart-bq.json, datasets, date expressions, LLM providers, environment variables |
| External data sources | Joining UltraCart data with your own BigQuery projects |
| Report delivery | Slack and email delivery |
| Report alarms | Threshold, percent-change, and missing-data alerts |
| Decks and dashboards | Combined PDFs and interactive HTML dashboards |
| Scheduling and automation | cron, GitHub Actions, service accounts |
| Managing multiple merchants | Agency and multi-store patterns |
| Troubleshooting | Error messages and what to do about them |
Related Documentation
- Getting started - install the CLI and produce a first report
- Data Warehouse (BigQuery) - enabling the warehouse, access, pricing, and table inventory
- Data Warehouse (BigQuery) + AI-Powered Reporting - how the in-app AI reporting tools fit together
- GitHub repository - source, issue tracker, and the developer-facing copies of these documents