> ## Documentation Index
> Fetch the complete documentation index at: https://costhq.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/installation">
    Install CostHQ with a single npm command and get tracking in under two minutes.
  </Card>

  <Card title="Quick Start" icon="bolt" href="/quickstart">
    Track your first agent session and open the dashboard in three steps.
  </Card>

  <Card title="Integrations" icon="plug" href="/integrations/openclaw">
    Connect CostHQ to OpenClaw, Claude Code, or any custom agent framework.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/reference/cli-overview">
    Every command, flag, and JSON output schema in one place.
  </Card>
</CardGroup>

## 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.

<Steps>
  <Step title="Install the CLI">
    ```bash theme={null}
    npm install -g costhq
    ```

    This gives you the `costhq` and `cs` CLI commands.
  </Step>

  <Step title="Track a session">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Open the dashboard">
    ```bash theme={null}
    cs dashboard
    ```

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

## 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

<CardGroup cols={2}>
  <Card title="Free" icon="circle-check">
    Full CLI, built-in pricing for 42+ models, local SQLite database, git integration, basic dashboard, session history, and budget alerts.
  </Card>

  <Card title="Pro — $12/month" icon="star" href="/configuration/pro-license">
    Spend Firewall, runaway agent alerts, shareable stats card, CSV export, activity heatmaps, file hotspots, and advanced analytics.
  </Card>
</CardGroup>

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