@hasna/economy

AI coding cost tracker for Claude Code, Takumi, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes. It ships as a CLI, MCP server, REST API, web dashboard, and native macOS menu bar app.

Features

• Ingests local Claude Code, Takumi, Codex, Gemini, OpenCode, Cursor, Pi, and Hermes usage.
• Tracks sessions, requests, projects, machines, models, cache tokens, cost centers, budgets, goals, and provider billing.
• Attributes usage to @hasna/accounts profiles when agents run under managed account/profile config dirs.
• Breaks down API-equivalent, metered API, subscription-included, estimated, and unknown cost by account, coding agent, and cost center.
• Seeds editable model pricing with input, output, cache-read, 5-minute cache-write, 1-hour cache-write, and context-cache storage rates.
• Handles tiered pricing such as Gemini long-prompt rates and OpenAI long-context rates.
• Reconciles estimates against Anthropic, OpenAI, and Gemini billing sources.
• Exposes cost data through CLI commands, an MCP server, REST endpoints, and a dashboard.
• Syncs project metadata from the @hasna/projects registry during full local sync.
• Sends budget alert webhooks and retries failed deliveries on later syncs.

Install

bun install -g @hasna/economy

Quick Start

economy sync --verbose
economy today
economy pricing list
economy serve --port 3456

Open the dashboard with:

economy dashboard --port 3456

Documentation

• CLI reference
• Ingestion sources and attribution
• Configuration, storage modes, and deployment
• REST API
• MCP server
• OTLP/HTTP sidecar

CLI Output Defaults

Economy CLI commands are compact by default so agent terminals do not fill their context with full records. High-cardinality list and status commands show essential columns, cap row counts, and print a hint when more rows are available.

Use explicit detail paths when you need more:

economy sessions --limit 50
economy session <id> --verbose
economy accounts month --json
economy usage month --verbose
economy todos list --limit 20
economy todos list --verbose
economy todos show 9.7

--json remains the machine-readable path for commands that support it. Human output may truncate rows or long text; use --json, --limit, or a show/detail command for complete data. --verbose expands output where supported; its exact limit is command-specific (for example, economy session --verbose shows up to 50 requests).

Status subcommands follow the same rule. For example, economy goal status prints a compact human summary by default and economy goal status --limit 5 or --verbose controls how many goals are listed.

Agent Integrations

Use the MCP server for live cost context inside coding agents:

economy mcp --all

That prints install snippets for Claude Code, Codex, and Gemini:

claude mcp add --transport stdio --scope user economy -- economy-mcp

Codex config:

[mcp_servers.economy]
command = "economy-mcp"
args = []

Gemini settings:

{
  "mcpServers": {
    "economy": { "command": "economy-mcp", "args": [] }
  }
}

The MCP server exposes read tools for summaries, sessions, machines, pricing, daily spend, budgets, goals, provider billing, usage snapshots, savings, project/account/agent/cost-center breakdowns, and subscriptions. MCP tools are compact by default for agent context safety; high-cardinality tools accept limit, verbose, or json=true where raw structured output is useful. It also exposes mutation tools for budgets, pricing rows, goals, and subscriptions so coding agents can manage Economy data through the same validated surface as the CLI and REST API. See the MCP guide for HTTP mode and the complete tool list.

Ingest

Run a full local ingest:

economy sync

Limit ingest to one source:

economy sync --claude
economy sync --codex
economy sync --gemini
economy sync --takumi
economy sync --opencode
economy sync --cursor
economy sync --pi
economy sync --hermes
economy sync --loops

economy sync --loops reads the OpenLoops store (~/.hasna/loops/loops.db by default, resolved through the @hasna/paths XDG data home once the loops store has migrated there) in read-only mode and imports OpenLoops orchestration/judge goal_runs.tokens_used into loop:* cost centers. It intentionally does not ingest dispatched coding-agent work from loops; heavy agent spend remains captured by the existing per-agent ingesters and can be analyzed alongside loop cost centers through account/profile attribution.

Useful repair options:

economy sync --force
economy sync --recalculate
economy sync --backfill-machine

Full sync also imports active project metadata from @hasna/projects when the registry is available. The Codex source reads both ~/.codex/state_5.sqlite and the Codewith store at ~/.codewith/state_5.sqlite by default; explicit HASNA_ECONOMY_CODEX_DB_PATH and HASNA_ECONOMY_CODEWITH_DB_PATH values override those locations.

Account attribution is automatic when @hasna/accounts has a matching active, applied, or env-dir profile for the agent. Account identity is the email address plus coding agent, so [email protected] under Codex and Claude is reported as two accounts. You can also force attribution for a process with ECONOMY_ACCOUNT=tool:name or agent-specific overrides such as ECONOMY_CODEX_ACCOUNT=codex:work.

Session drilldown can be scoped to an account key, account name, or email:

economy sessions --account [email protected]
economy accounts month
economy breakdown --by account

Account breakdowns report api_equivalent_usd for the API list-price value of the usage, plus billable_usd/metered_api_usd for known direct API spend and subscription_included_usd for usage covered by a subscription.

Cost-center breakdowns group spend across loops, apps, repos, services, and teams:

economy breakdown --by cost-center
economy breakdown --by loop
economy breakdown --by app
economy breakdown --by repo

Apps and services can report usage through the local economy-otel sidecar:

economy-otel --port 4318
curl -X POST http://127.0.0.1:4318/ingest \
  -H 'content-type: application/json' \
  -d '{"source":"app","cost_center":"alumia","cost_center_kind":"app","project_path":"/workspace/alumia","model":"gpt-5-mini","cost_usd":0.12,"input_tokens":1200,"output_tokens":300}'

Accepted /ingest attribution fields include cost_center, cost_center_kind, cost_center_id, attribution_tag, project_path, repo, account_key, account_tool, account_name, account_email, and explicit cost_usd. The OTLP guide documents both payload formats and all aliases.

Subscription plans can be configured locally and are used by savings calculations:

economy subscriptions set --provider cursor --plan pro --fee 20 --included 20 --agent cursor
economy subscriptions list
economy savings month
economy usage month --agent cursor

Pricing

Default pricing is seeded into SQLite and can be edited locally:

economy pricing list
economy pricing set gpt-5.4 --input 2.50 --output 15 --cache-read 0.25
economy pricing set claude-sonnet-4-6 --input 3 --output 15 --cache-read 0.30 --cache-write 3.75 --cache-write-1h 6
economy pricing set gemini-3.1-pro-preview --input 2 --output 12 --cache-read 0.20 --cache-storage 4.50

Pricing supports separate cache-read, 5-minute cache-write, 1-hour cache-write, and context-cache storage rates. Custom user-edited rows are preserved when default pricing seeds are repaired or updated.

Provider-qualified rows such as z-ai/glm-5.1 or minimax/minimax-m2.7 are matched before unqualified rows, so router-specific prices can coexist with direct provider API prices.

OpenRouter-style model IDs ending in :free are treated as zero-cost variants even when their base model has a paid default row.

Billing

Estimated costs can be reconciled with provider billing in local mode:

economy billing sync --days 31
economy billing show --period month

Supported billing sources:

• Anthropic: HASNAXYZ_ANTHROPIC_LIVE_ADMIN_API_KEY or ANTHROPIC_ADMIN_API_KEY
• OpenAI: HASNAXYZ_OPENAI_LIVE_ADMIN_API_KEY or OPENAI_ADMIN_API_KEY
• Gemini: HASNA_ECONOMY_GEMINI_BILLING_EXPORT_PATH, legacy HASNAXYZ_ECONOMY_GEMINI_BILLING_EXPORT_PATH, or GEMINI_BILLING_EXPORT_PATH

Gemini billing export files may be JSON arrays, JSON objects with rows, JSONL, or simple CSV.

Budgets, Goals, And Alerts

economy budget set --period monthly --limit 50 --alert 80
economy budget set --agent codex --period weekly --limit 25 --alert 70
economy budget set --cost-center loop:fleet-evaluator --period weekly --limit 10
economy budget list
economy goal set --period month --limit 40
economy goal set --agent gemini --period week --limit 15
economy goal list
economy config set webhook-url https://example.com/economy-webhook
economy config webhook-test

Budgets can be global, project-scoped with --project, agent-scoped with --agent, cost-center scoped with --cost-center, or combined. Goals can be global, project-scoped, agent-scoped, or both. Valid agent scopes are claude, takumi, codex, gemini, opencode, cursor, pi, and hermes.

Budget webhooks fire after sync when the alert threshold is crossed. Failed webhook deliveries are not marked as fired, so the next sync can retry them.

REST API

Start the server:

economy-serve --port 3456

The canonical API uses /v1; /api remains a legacy alias for the dashboard and older clients. For example:

• GET /health, /ready, /version, and /openapi.json
• GET /v1/summary?period=today
• GET /v1/sessions?agent=codex&[email protected]&limit=20
• GET /v1/breakdown?by=cost-center&period=month
• POST /v1/budgets, /v1/goals, /v1/pricing, and /v1/subscriptions
• POST /v1/sync, /v1/billing/sync, and /v1/ingest

See the REST API reference for every route, response envelopes, authentication, and legacy aliases. The server publishes the current generated contract at /openapi.json.

The server also serves the built dashboard when dashboard/dist is present. The dashboard includes account-scoped session filtering, subscription plan create/update/delete controls in Savings, and savings/usage/account tables for subscription-aware cost analysis.

Native macOS Menubar

The menubar/ app is a native SwiftUI MenuBarExtra app, not Electron. It targets Swift 5.9+ and macOS 14+, and talks to the REST API exposed by economy-serve. It shows today/week/month spend, token and request counts, top agents, top accounts, top projects, active subscription plans, subscription savings, multi-agent usage snapshots, recent sessions, and fleet status. The default server URL is http://127.0.0.1:3456.

Build it on macOS:

cd menubar
swift build -c release

Release app helpers:

economy menubar install
economy menubar start
economy menubar stop
economy menubar uninstall

Data Directory

Data is stored under a single data root resolved through the @hasna/paths resolver (XDG/macOS home layout). The legacy ~/.hasna/economy/ stays the effective root until the store is actually migrated to the XDG data home or the operator sets the data-kind override HASNA_DATA_HOME; the exact-app overrides HASNA_ECONOMY_HOME / ECONOMY_HOME win unconditionally.

The main SQLite database lives at <data-root>/economy.db (~/.hasna/economy/economy.db by default). Older ~/.economy/ data is copied on first open when the new directory does not exist. Override the database path with HASNA_ECONOMY_DB_PATH or ECONOMY_DB.

For shared deployments, CLI and MCP can use a remote /v1 API instead of local SQLite by setting HASNA_ECONOMY_API_URL and HASNA_ECONOMY_API_KEY. See configuration for client resolution, server auth, Postgres mode, and all environment variables.

Development

bun test
bun run typecheck
bun run build
bun scripts/sync-openapi.ts
cd dashboard && bun run lint
cd menubar && swift build -c release

Open Source

Economy is published under the Apache-2.0 license. See CONTRIBUTING.md for local development and release hygiene, SECURITY.md for vulnerability reporting, CODE_OF_CONDUCT.md for community expectations, and CHANGELOG.md for release notes.

License

Apache-2.0 -- see LICENSE