Skip to main content
Any script that makes AI API calls can be tracked with CostHQ — no SDK changes, no framework lock-in. Pick the integration approach that fits how your agent already runs.

​
Four Integration Approaches

cs run

Zero configuration. Wrap your command and CostHQ handles the full session lifecycle automatically.

Proxy + env vars

Start the local proxy, set two environment variables, and every AI call your script makes is logged automatically.

CI/CD pipeline

Add cs start and cs end to your pipeline steps to track every build and test run.

Git hooks

Use a post-commit hook to trigger tracking actions whenever your agent commits code.

​
Approach 1: cs run

cs run is the zero-configuration option. It starts a session, launches a local proxy pre-configured with the right environment variables, runs your command, and prints a cost summary when it exits — all in one step. 
cs run python my_agent.py
cs run node agent.js
cs run -- npx my-agent --task "fix the bug"
What happens in sequence:
  1. A new session is created (name defaults to the command string)
  2. A local proxy starts on port 3739
  3. Your command launches with ANTHROPIC_BASE_URL and OPENAI_BASE_URL already pointing at the proxy
  4. All AI API calls are intercepted and logged to the session
  5. When the command exits, the session ends and a summary is printed

​
Approach 2: Proxy + Environment Variables

If you need more control over session boundaries, start the proxy manually and set the environment variables yourself before running your agent: 
cs proxy --session "agent run" &
export ANTHROPIC_BASE_URL=http://127.0.0.1:3739
python my_agent.py
cs end
This works with any tool or script that makes Anthropic or OpenAI API calls — not just scripts wrapped with cs run.

​
Approach 3: CI/CD Pipeline Tracking

Track every build and test pipeline by wrapping your pipeline steps with cs start and cs end: 
cs start "CI Build #${BUILD_NUMBER}"
npm run build && npm test
cs end -n "Build result: $?"
The exit code of your build command is captured as a note so you can see pass/fail alongside cost in the dashboard.

​
Approach 4: Git Hooks

For agents that commit code, use a post-commit hook to run tracking actions after each commit. Add the following to .git/hooks/post-commit: 
#!/bin/sh
cs status > /dev/null 2>&1
if [ $? -eq 0 ]; then
  echo "Commit logged to active session"
fi

​
Concurrency and Multiple Repos

Multiple agents or repos on the same machine can safely run at the same time. CostHQ uses SQLite WAL mode so concurrent writes never block each other. Use --close-stale to avoid conflicts when starting a new session, and use -s <id> to target a specific session when logging from a separate process: 
# Terminal 1 — repo A
cd ~/project-a && cs start "Fix bug" --close-stale
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 5000 --completion-tokens 1000

# Terminal 2 — repo B, target session 42 explicitly
cd ~/project-b && cs start "Add feature" --close-stale
cs log-ai -p openai -m gpt-4o -t 8000 -c 0.04 -s 42

​
Crash Resilience

If an agent dies mid-session, the next cs start won’t leave orphaned sessions behind: 
cs start "Continue work" --resume      # resume the existing session for this directory
cs start "Fresh start" --close-stale   # auto-close all stale sessions, then start fresh
cs recover --max-age 12                # bulk-end all sessions older than 12 hours
Build your agent around this five-step sequence to get reliable, machine-readable output at every step:
  1. cs start "task" --close-stale --json → capture the session ID from the response
  2. cs note "phase 1: analysis" --json → add a timestamped annotation
  3. Agent performs its work (files and git commits are tracked automatically)
  4. cs log-ai -p <provider> -m <model> --prompt-tokens <n> --completion-tokens <n> --json → log each AI call
  5. cs end -n "summary" --json → finalize the session and get the full cost totals
# Step 1 — start and capture session ID
SESSION=$(cs start "Refactor auth module" --close-stale --json | jq -r '.id')

# Step 2 — annotate phases
cs note "phase 1: analysis" --json

# Step 4 — log each AI call after it completes
cs log-ai -p anthropic -m claude-sonnet-4 \
  --prompt-tokens 8000 --completion-tokens 2000 --json

# Step 5 — end and print totals
cs end -n "Refactored auth, 4 tests added" --json

​
Failsafe: When cs Is Not Installed

Always check whether cs is available before trying to track. If CostHQ isn’t installed, skip tracking and let the agent continue its primary task: 
which cs >/dev/null 2>&1 || { echo "costhq not installed, skipping"; }
On Windows, use where cs instead of which cs. All cs commands work identically on Windows, macOS, and Linux.

​
Further Reading

  • JSON Output Reference — full schema for every --json response, including schemaVersion, error shapes, and exit codes
  • Node.js Programmatic API — the AgentSession class and runAgentSession helper for embedding CostHQ directly in your Node.js agent code