CostHQ: Know What Your AI Agents Actually Cost

CostHQ is an open-source AI agent cost tracking and LLM spend monitoring tool. Track API token spend, local model compute costs, file changes, and git commits locally with zero telemetry.

CostHQ gives you full visibility into what every AI agent run costs. Install the CLI, wrap your agent command with cs run, and instantly see duration, files touched, commits made, and exact API spend — all stored locally in SQLite, nothing sent to the cloud.

Installation

Install CostHQ with a single npm command and get tracking in under two minutes.

Quick Start

Track your first agent session and open the dashboard in three steps.

Integrations

Connect CostHQ to OpenClaw, Claude Code, or any custom agent framework.

CLI Reference

Every command, flag, and JSON output schema in one place.

How CostHQ works

CostHQ intercepts AI API calls through a local proxy and records them to a SQLite database on your machine. You never send data anywhere — there is no account, no cloud sync, and no telemetry.

1. Install the CLI

   npm install -g costhq
   

   This gives you the costhq and cs CLI commands.

2. Track a session

   cs run python my_agent.py
   

   CostHQ starts a session, spins up the local proxy, runs your command, and prints a cost summary when the process exits.

3. Open the dashboard

   cs dashboard
   

   A local web UI opens at http://localhost:3737 showing cost trends, model usage, session history, and budget alerts.

What gets tracked

Signal	How it’s captured
AI tokens & cost	Local proxy intercepts Anthropic and OpenAI API calls
Session duration	Start/end timestamps with millisecond precision
File changes	Filesystem watcher scoped to the repo root
Git commits	Polling git log every 10 seconds during the session

Free vs Pro

Free

Full CLI, built-in pricing for 42+ models, local SQLite database, git integration, basic dashboard, session history, and budget alerts.

Pro — $12/month

Spend Firewall, runaway agent alerts, shareable stats card, CSV export, activity heatmaps, file hotspots, and advanced analytics.

All data is stored in ~/.costhq/sessions.db on your machine. CostHQ never phones home and never stores your API keys.