Skip to main content
CostHQ ships as an OpenClaw skill, so the agent tracks itself — every task gets a session, every AI call gets logged, and every cost gets recorded without a single manual command.

​
Quick Install

1

Install the CostHQ CLI

npm install -g costhq
2

Install the skill via ClawHub

clawhub install CostHQ
3

Start a new OpenClaw session

That’s it. Start a new OpenClaw session and tracking begins automatically.
If you don’t have ClawHub, copy the skill directly from the global npm package:
cp -r $(npm root -g)/costhq/skills/CostHQ ~/.openclaw/skills/

​
What the Skill Does Automatically

Once installed, the OpenClaw agent runs these steps on your behalf — no configuration needed:
  1. Runs cs start "task name" at the beginning of each task
  2. Logs API usage with cs log-ai after each AI call
  3. Checks costs with cs status --json during long tasks
  4. Runs cs end when the task completes

​
Example Agent Transcript

Here’s what a tracked OpenClaw session looks like in practice, using a real payment-bug fix as an example: 
You: Fix the payment processing bug and add retry logic

Agent: Starting session tracking...
  $ cs start "Fix payment processing + retry" --close-stale --json
  {"schemaVersion":1,"id":12,"name":"Fix payment processing + retry","status":"active",...}

  $ cs note "analyzing existing retry implementation" --json
  {"id":1,"sessionId":12,"message":"analyzing existing retry implementation",...}

  [reads src/payments.ts, src/retry.ts, identifies the bug]

  $ cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json
  {"logged":{"provider":"anthropic","model":"claude-sonnet-4","tokens":10000,"cost":0.054},"session":{"id":12,"aiCost":0.054,"aiTokens":10000}}

  [edits src/payments.ts — fixes null check]

  $ cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 12000 --completion-tokens 4000 --json
  {"logged":{"provider":"anthropic","model":"claude-sonnet-4","tokens":16000,"cost":0.096},"session":{"id":12,"aiCost":0.15,"aiTokens":26000}}

  [writes retry logic with exponential backoff, runs tests]

  $ cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 5000 --completion-tokens 2000 --json
  {"logged":{"provider":"anthropic","model":"claude-sonnet-4","tokens":7000,"cost":0.045},"session":{"id":12,"aiCost":0.195,"aiTokens":33000}}

  $ cs note "tests passing, committing" --json

  $ cs end -n "Fixed payment bug, added exponential backoff retry" --json
  {"id":12,"status":"completed","durationFormatted":"9m","filesChanged":3,"commits":1,"aiCost":0.195}

  Done — 9 minutes, 3 files, 1 commit, $0.20 total.

​
After 50 Agent Runs

Run cs stats at any time to see aggregated totals across all sessions: 
$ cs stats

┌───────────────────┬────────────────┐
│ Total Sessions    │ 50             │
│ Total Time        │ 8h 34m         │
│ Files Changed     │ 312            │
│ Commits           │ 87             │
│ Total AI Cost     │ $47.23         │
└───────────────────┴────────────────┘

​
Key Flags for Agents

FlagWhy
--jsonMachine-readable output on every command
--close-stalePrevents session_active errors from prior crashes
--prompt-tokens / --completion-tokensAuto-calculates cost from the built-in pricing table
-s <id>Targets a specific session for multi-repo safety

​
Failsafe: When cs Is Not Installed

The skill checks whether cs is available before attempting to track. If CostHQ isn’t installed, the agent skips tracking and continues with its primary task — your work is never blocked: 
which cs >/dev/null 2>&1 || { echo "costhq not installed, skipping tracking"; }
On Windows, use where cs instead of which cs. All cs commands work identically on Windows, macOS, and Linux.