Metadata-Version: 2.4
Name: cost-audit-agent
Version: 0.4.0
Summary: Solo Founder OS agent #11 — monthly bill audit across Vercel / Anthropic / Supabase / OpenPanel / HyperDX. Flags underused SaaS + spend spikes.
Author-email: Alex Ji <alex@vibexforge.com>
License: MIT
Project-URL: Repository, https://github.com/alex-jb/cost-audit-agent
Project-URL: Issues, https://github.com/alex-jb/cost-audit-agent/issues
Project-URL: Homepage, https://github.com/alex-jb/cost-audit-agent
Keywords: billing,audit,vercel,anthropic,indie,saas
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: solo-founder-os>=0.3.0
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: mcp>=1.0; extra == "dev"
Dynamic: license-file

# cost-audit-agent

**English** | [中文](README.zh-CN.md)

> Solo Founder OS agent #11 — monthly bill audit across the SaaS stack indie founders use. Flags underused subscriptions, spend spikes, and specific waste recommendations with estimated dollar savings.

[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/cost-audit-agent.svg)](https://pypi.org/project/cost-audit-agent/)
[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](#)

Built by [Alex Ji](https://github.com/alex-jb). Born from this thought:

> *I'm subscribed to 14 SaaS tools. I have no idea which I actually use enough to justify. The 2nd of every month I should know exactly what's worth keeping.*

## What it does

Pulls month-to-date usage + spend from each provider, runs heuristics, outputs a markdown report with specific dollar-tagged recommendations:

```
## 🔍 Waste findings — potential savings: $42.00/mo

- ⚠️ **[vercel]** Vercel Pro underused (~$20.00/mo)
  - Only 3 deployment(s) this month on a $20.00/mo Pro plan. If you can wait 45s
    longer per build, the Hobby plan is free.

- 💡 **[anthropic]** Sonnet-heavy usage — consider Haiku for routine tasks (~$22.00/mo)
  - 73 Sonnet 4.6 calls ($33.40) vs only 12 Haiku calls. For diff review, summary,
    classification — Haiku is 3× cheaper with comparable quality.
```

## Install

```bash
git clone https://github.com/alex-jb/cost-audit-agent.git
cd cost-audit-agent
pip install -e .
cp .env.example .env  # fill in VERCEL_TOKEN etc.
```

## Usage

```bash
# One-shot report to stdout
cost-audit-agent

# Write to your Obsidian vault on the 2nd of each month (cron-friendly)
cost-audit-agent --out ~/Documents/Obsidian/.../cost-$(date +%Y-%m).md

# Limit to one provider
cost-audit-agent --provider vercel
```

## Providers (v0.1)

| Provider | What it reads | Auth |
|---|---|---|
| **vercel** | deployments + build-minute estimate + Pro-plan baseline | `VERCEL_TOKEN` |
| **anthropic** | local agent usage logs (`~/.build-quality-agent/usage.jsonl`, `~/.funnel-analytics-agent/usage.jsonl`); org-wide if admin key provided | optional `ANTHROPIC_ADMIN_KEY` + `ANTHROPIC_ORG_ID` |

## Why local-logs fallback for Anthropic

Anthropic's organization billing API requires an admin-scoped key, which most indie founders don't bother creating. But build-quality-agent and funnel-analytics-agent both write per-call usage to `~/.<agent>/usage.jsonl`. For a solo founder running 2-3 agents, those logs cover ~95% of monthly Anthropic spend. We aggregate them by month with the published Haiku/Sonnet/Opus prices.

## Roadmap

- [x] **v0.1** — Vercel + Anthropic providers · markdown report · waste heuristics · 14 tests
- [x] **v0.3** — OpenPanel, HyperDX, Supabase, GitHub Actions providers
- [x] **v0.4** — MCP server: query monthly spend + top savings from Claude Desktop
- [ ] **v0.5** — 3-month trailing baseline · spike detection
- [ ] **v0.6** — Claude-summarized executive narrative at top of report
- [ ] **v0.7** — Auto-cancel button (one-click webhook to provider's cancel endpoint when finding savings > $10/mo, gated by HITL like vc-outreach)

## MCP server (Claude Desktop / Cursor / Zed)

Ask your AI assistant "what's my biggest waste this month?" and let it call the auditor.

```bash
pip install 'cost-audit-agent[mcp]'
```

Then in `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cost-audit": {
      "command": "cost-audit-mcp",
      "env": {
        "VERCEL_TOKEN": "...",
        "VERCEL_PLAN_USD": "20",
        "ANTHROPIC_ADMIN_KEY": "...",
        "ANTHROPIC_ORG_ID": "...",
        "OPENPANEL_CLIENT_ID": "...",
        "OPENPANEL_CLIENT_SECRET": "...",
        "HYPERDX_API_KEY": "...",
        "SUPABASE_PERSONAL_ACCESS_TOKEN": "...",
        "SUPABASE_PROJECT_REF": "...",
        "GITHUB_TOKEN": "...",
        "GITHUB_REPO": "alex-jb/vibex"
      }
    }
  }
}
```

Tools:
- `get_monthly_report()` — full markdown audit, all providers
- `get_provider(name)` — one provider's spend + waste findings
- `top_savings(n=5)` — top N findings by estimated $/mo, sorted

## License

MIT.
---

## 🧩 Part of the [Solo Founder OS](https://github.com/alex-jb/solo-founder-os) stack

A growing collection of MIT-licensed agents that share `solo-founder-os` as their base — cron, eval, reflexion, AnthropicClient, HITL queue, notifiers. Each agent is independently useful; together they cover the full one-person company workflow.

🌐 The whole stack is live in production at [vibexforge.com](https://vibexforge.com).

| Agent | What it does |
|---|---|
| [solo-founder-os](https://github.com/alex-jb/solo-founder-os) | The shared base lib (cron · eval · reflexion · skill library · DGM-lite). Every other agent depends on it. |
| [build-quality-agent](https://github.com/alex-jb/build-quality-agent) | Pre-push Claude diff reviewer + local build runner — catches CI-killing changes before they ship. |
| [customer-discovery-agent](https://github.com/alex-jb/customer-discovery-agent) | Reddit pain-point scraper + Claude clustering for product validation. |
| [funnel-analytics-agent](https://github.com/alex-jb/funnel-analytics-agent) | Daily founder brief + real-time PH-day alerts across 9 sources. |
| [orallexa-marketing-agent](https://github.com/alex-jb/orallexa-marketing-agent) | AI marketing agent — submit project once, get platform-native posts for X / Reddit / HN / Dev.to / 小红书 + 7 more. Powers [vibexforge.com](https://vibexforge.com). |
| [vc-outreach-agent](https://github.com/alex-jb/vc-outreach-agent) | Cold email drafter — investors (vc mode) or paying customers (customer mode, merged from customer-outreach in v0.9.0). HITL queue + SMTP sender. |
| [bilingual-content-sync-agent](https://github.com/alex-jb/bilingual-content-sync-agent) | EN ⇄ 中文 i18n diff + Claude translate + HITL apply. Batch API path @ 50% off. |
| [customer-support-agent](https://github.com/alex-jb/customer-support-agent) | Triage user messages → auto-draft replies → HITL queue. Closes the L5 customer-support layer. |
| [payments-agent](https://github.com/alex-jb/payments-agent) | Overdue-invoice reminder drafter. Stripe-shaped types + MockProvider fallback + hard money-safety prompt rules. |

*Each agent's own row is omitted from its README. Install whichever solve real problems for you — `pip install <agent-name>`.*
