StackAudit is an open-source AI Cost Intelligence platform that helps engineering teams track AI API usage, attribute spending to workloads, and understand the cost of producing meaningful outcomes.
Quick Start · Documentation · How It Works · Feature Matrix · Report a Bug · Contribute
Instead of looking at AI spending as one large invoice at the end of the month, StackAudit helps you investigate:
- Which workloads are consuming your AI budget? Separate customer-facing copilot traffic from background batch jobs, evaluations, and internal tooling.
- What does each workflow cost per outcome? Calculate true unit economics, such as the exact AI cost to resolve a customer ticket, summarize a document, or onboard a user.
- Where is usage increasing unexpectedly? Spot consumption surges and token anomalies before they compound on your provider bills.
- Which costs are unattributed or insufficiently priced? Identify orphaned API keys and verify that token rates accurately capture prompt caching savings.
- Where should engineering teams investigate optimization opportunities? Pinpoint workloads experiencing model drift, excessive prompt token bloat, or low cache hit rates.
Built for AI-native startups, developers, and engineering teams.
| Question | Answer |
|---|---|
| What is StackAudit? | An open-source, local-first cost intelligence platform and analytics dashboard for AI engineering workloads. |
| What problem does it solve? | AI provider invoices are black boxes: they aggregate total token spend across thousands of requests with zero visibility into which feature or business workflow incurred the cost. StackAudit attributes token spend to specific engineering workloads and correlates costs with actual business outcomes. |
| Who should use it? | AI engineers, tech leads, engineering managers, and founders deploying OpenAI and Anthropic models who need visibility into their unit economics. |
| How does it work? | You import usage records via CSV or REST API. StackAudit normalizes usage across providers, applies versioned reference pricing with arbitrary decimal precision (big.js), maps usage to workloads via attribution rules, and calculates Cost Per Outcome (CPO). |
| How can I install it? | Run 4 commands with Docker and Node.js (npm ci, npx supabase start, npm run setup, npm run dev) to have a complete dashboard running locally in under 3 minutes. |
| How can I contribute? | Fork the repo, review our Contributing Guide, pick up an issue, or add reference pricing fixtures for new models. |
| Metric / Dimension | Sample Value | Attribution / Heuristic Context |
|---|---|---|
| Total AI Spend (30D) | $1,482.35 | Bounded 30-day window; calculated with big.js arbitrary precision. |
| Token Consumption | 412.8M tokens | 48.2% prompt cache hit rate across Anthropic & OpenAI workloads. |
| Cost Per Outcome (CPO) | $0.042 / outcome | Primary metric: Customer Support Copilot (ticket_resolved). |
| Attributed Workloads | 100% Attributed | Support Copilot (42.5%), Document Extraction (31.2%), Code Review Agent (18.1%). |
| Active Anomalies | 2 Requiring Attention | 1 High Severity (COST_DRIFT), 1 Medium Severity (EFFICIENCY). |
flowchart LR
A[Usage Records<br/>CSV Import / API] --> B[Canonical Normalization<br/>core/providers]
B --> C[Effective-Dated Pricing<br/>core/pricing]
C --> D[(usage_events)]
E[Attribution Rules<br/>core/workloads] --> F[Attributed Workload Ledger]
D --> F
G[Outcome Events<br/>POST /api/v1/outcomes] --> H[Cost Per Outcome Engine<br/>core/outcomes]
F --> H
F --> I[Audit & Anomaly Detector<br/>core/audit]
I --> J[Actionable Alerts<br/>core/monitoring]
- Ingest & Normalize: Provider records are normalized into canonical events capturing standard input/output tokens and prompt caching tokens (read & creation).
- Precision Pricing: Effective-dated rate cards calculate exact monetary costs with
big.jsdecimal arithmetic, preventing sub-cent floating-point rounding errors. - Dynamic Attribution: API key rules map usage events to business workloads without altering raw historical usage records.
- Outcome Correlation: Workload expenditures are correlated against business events to calculate clean unit economics (Cost Per Outcome).
- Heuristic Audits: Rule engines detect anomalies like unexpected token spikes, cost drift, prompt bloat, and model tier mix changes.
- ✅ Multi-Model Reference Pricing: Pre-configured pricing catalog for OpenAI and Anthropic models with effective dating support.
- ✅ Prompt Caching Economics: Accurately accounts for cached input reads vs. cache creation writes to reflect true vendor invoices.
- ✅ Arbitrary-Precision Financial Math: Engineered with
big.jsto ensure financial figures are exact down to fractional cents. - ✅ Workload Attribution: Map provider API keys to specific business workflows, teams, or services.
- ✅ Cost Per Outcome (CPO) Metrics: Track unit costs like cost per customer resolution, cost per legal document parsed, or cost per user onboarding.
- ✅ Evidence-Based Auditing: Automated detection across 4 categories:
USAGE_SPIKE,COST_DRIFT,TOKEN_EFFICIENCY, andMODEL_MIX. - ✅ Interactive Usage Explorer: Filter usage by date ranges, providers, models, and workloads with server-side pagination.
- ✅ Deterministic 90-Day Demo: Includes a synthetic data generator creating a realistic 90-day operational history with one command.
Important
StackAudit V0 is a single-user, local-first evidence ledger.
It is designed to run exclusively on an operator's workstation (127.0.0.1) or within an explicitly controlled, isolated private network boundary.
It is NOT a public multi-tenant SaaS application.
- Localhost Binding: Next.js binds strictly to
127.0.0.1:3000by default. Wildcard host binding (0.0.0.0) is prohibited in local mode. - Single Operator Workspace: All operations are explicitly scoped to
STACKAUDIT_WORKSPACE_ORG_ID. The application never selects an organization implicitly. - No Multi-Tenancy: The current release does not include multi-tenant user authentication, user sessions, or team RBAC. Service-role database access bypasses PostgreSQL RLS.
- Safe Ingestion: Supported via offline canonical CSV upload in the UI and programmatic REST API. It does not require or store your OpenAI/Anthropic API keys.
See DEPLOYMENT.md and SECURITY.md for exhaustive details on deployment boundaries, security guardrails, and future multi-tenancy requirements.
Follow this sequence to set up a clean, fully populated instance on your machine.
- Node.js:
>= 22.22.2and npm - Docker: Docker Desktop (or running Docker daemon)
- Supabase CLI: Included in dependencies; run via
npx supabase
git clone https://github.com/nitin-kumar-code/StackAudit-Core.git
cd StackAudit-Core/stackaudit
npm ci# Start local Supabase Postgres instance
npx supabase start
# Copy sample environment configuration
cp .env.example .env.localRetrieve your local credentials by running npx supabase status. Update .env.local with your service_role key:
STACKAUDIT_DEPLOYMENT_MODE=local
STACKAUDIT_DATABASE_MODE=local
NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
SUPABASE_SERVICE_ROLE_KEY=<service_role_key_from_supabase_status>
STACKAUDIT_WORKSPACE_ORG_ID=8a775c7f-e31c-8f9b-9000-000000000001# 1. Apply database migrations
npx supabase db reset
# 2. Load pricing fixtures and seed 90 days of demo data
npm run setupnpm run devOpen http://localhost:3000 in your browser to explore your local StackAudit instance!
All commands are executed from within the stackaudit/ directory:
| Command | Description |
|---|---|
npm run dev |
Starts the Next.js development server at http://localhost:3000 |
npm run setup |
Complete setup: loads pricing fixtures and seeds the demo dataset |
npm run pricing:load |
Loads reference pricing fixtures (fixtures/pricing/reference-pricing-v1.json) |
npm run seed |
Seeds deterministic 90-day demo usage, workloads, outcomes, and alerts |
npm run typecheck |
Verifies TypeScript types across the entire project |
npm run lint |
Runs ESLint rules and code style checks |
npm test |
Runs the Vitest unit test suite |
npm run test:integration |
Runs Supabase database integration tests |
npm run build |
Builds the production Next.js application bundle |
Comprehensive documentation is available in the docs/ directory:
- 📖 Installation Guide: Exhaustive setup instructions, system prerequisites, and troubleshooting.
- ⚙️ Configuration Reference: Environment variables, seed customization, and database security modes.
- 🏗️ Architecture & Data Model: Internal subsystems, canonical records, and financial calculation semantics.
- 🔌 REST API Reference: Detailed endpoints, request/response contracts, and query bounds.
- 🖥️ Self-Hosting Guide: Operational guide for local self-hosting and deployment boundaries.
- 🗄️ Database & Migrations: Schema inventory, Postgres RPC aggregation functions, and indexing strategy.
- Streaming Proxy & Client SDK: Lightweight TypeScript and Python wrappers for real-time request tagging.
- Automated Provider Sync: Secure scheduled imports from OpenAI and Anthropic usage reporting APIs.
- Alert Webhooks: Native notification integrations for Slack, Discord, and PagerDuty.
- Multi-User Authentication: Team accounts, organization switching, and role-based access control (RBAC).
- Model Benchmark Overlays: Contextualizing workload costs against quality/speed benchmark indexes.
We welcome contributions from the community! Whether you are reporting a bug, proposing new unit metrics, or adding pricing models, please check out our:
In the spirit of transparency: portions of StackAudit—including architectural documentation, test suites, reference pricing fixtures, and security hardening—were developed with the assistance of AI engineering tools (Claude Code and Google Antigravity). All AI-assisted contributions are architected, audited, verified against automated test suites, and reviewed by human engineers.
StackAudit is open-source software licensed under the Apache License, Version 2.0.