shield_lock
JinDaGe
← Back to skills
extension
Category: OtherNo API key required

CostHQ

Track agent session costs, file changes, and git commits with CostHQ. Enforces budget limits, tracks local models, and provides Enterprise SOC2 audit trails...

personAuthor: brian-mwirigihubclawhub
open_in_newRepositorydownloadDownload package

Session Cost Tracking (CostHQ)

Track agent session costs, file changes, and git commits. Enforces budget limits, tracks local models (Ollama, vLLM), and provides detailed session analytics with a full web dashboard and tamper-evident SOC2 audit logging for Enterprise users.

Latest: v4.0.0 - Added Semantic Caching Proxy and Granular Session Termination.

📦 npm • ⭐ GitHub • 📝 Changelog

Installation

# 1. Install the CLI globally from npm
npm install -g costhq

# 2. Install the OpenClaw skill
clawhub install costhq

After installing, the cs command is available globally. The OpenClaw agent will automatically use it to track sessions.

Requirements: Node.js 18+ and C/C++ build tools (needed to compile the embedded SQLite module).

| OS | Install build tools | |---|---| | Ubuntu/Debian | sudo apt-get install -y build-essential python3 | | macOS | xcode-select --install | | Windows | npm install -g windows-build-tools or install Visual Studio Build Tools | | Alpine | apk add build-base python3 |

Data is stored locally at ~/.costhq/sessions.db (or ~/.CostHQ).

When to use

  • Always start a tracked session at the beginning of a multi-step task
  • Always log AI usage after each API call you make
  • Always end the session when the task is complete
  • Use cs dashboard to review session data, set up local models, or verify the audit trail (Enterprise).

Commands

Start tracking

# Agent mode (always use --json for structured output):
cs start "task description" --json --close-stale

# Resume if a session was left open (e.g. after a crash):
cs start "task description" --json --resume

Log AI usage (after each API call)

# Standard cloud model (cost auto-calculated):
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json

# Local model with compute duration (NEW in v3.3.0):
# Use --duration in seconds (120) or string (2m30s). Cost is based on registered $/hr rate.
cs log-ai -p ollama -m llama3 --tokens 4500 --duration 2m30s --local --json

# With all fields:
cs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent "Research Agent" --json

Agent Name: Use --agent "Agent Name" to track which agent performed the work. Local Models: You can track self-hosted models (Ollama, llama.cpp, vLLM) by registering a GPU hourly rate in the dashboard. Use --duration and --local when logging.

Check current status

cs status --json

End session and get summary

cs end -n "completion notes" --json

Ending the session automatically logs an audit event (Enterprise) and scans git for files/commits.

Web Dashboard

cs dashboard

The dashboard shows:

  • Overview — KPIs, daily trends, cost velocity, and the Semantic Caching Proxy toggle.
  • Command Center — Real-time CLI execution and granular termination of individual sessions.
  • Sessions — searchable/sortable table, per-session details.
  • Local Models — Register compute rates ($/hr) for Ollama, vLLM, etc.
  • Compliance — View the tamper-evident cryptographic SOC2 audit chain and configure Team Identities (Enterprise only).
  • Pro Ops — Manage licensing, PDF exports, and sync features.

Semantic Caching Proxy

To save money, CostHQ includes a Semantic Caching Proxy that intercepts API calls and returns cached responses for identical requests:

cs proxy start --port 3739

Or toggle it directly from the Overview page in the dashboard. Route your tools via OPENAI_BASE_URL=http://127.0.0.1:3739/openai/v1.

View historical stats and details

cs show --json --files --commits
cs stats --json
cs export --format json --limit 10

Add notes / annotations

cs note "Tests passing, moving to cleanup" --json

Agent Workflow

Agents should always use --json on every command for structured, parseable output.

  1. At task start: cs start "Fix authentication bug" --json --close-stale
  2. Add context notes: cs note "analyzing auth flow" --json
  3. After each AI call: cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 800 --completion-tokens 200 --agent "Bug Fixer" --json
  4. If using a local model: cs log-ai -p ollama -m mistral --tokens 1000 --duration 45s --local --json
  5. At task end: cs end -n "Fixed the auth bug" --json

Budget & Pricing

  • Standard pricing is configurable via cs pricing set my-model 5.00 15.00.
  • Local model pricing (compute-based) is configured in the cs dashboard under Local Models.
  • Check cs status --json before expensive operations.

Important

  • Always use --json on every command — agents must use structured output.
  • Use --close-stale on cs start to clear crashed sessions.
  • In Enterprise mode, a cryptographic hash chain automatically logs session starts, ends, data resets, and AI usage.