Installation - CostHawk Documentation

Quick Setup

macOS / Linux

Recommended command:

npm exec --yes costhawk@latest -- --login

This opens browser approval and writes MCP config automatically.

Windows

Use the same login flow:

npm exec --yes costhawk@latest -- --login

One hybrid token with scopes: mcp:read, mcp:write, otel:ingest
Claude MCP config written automatically
Optional OpenCode config if selected in setup prompts

Verify Installation

After setup, verify it worked:

npm exec --yes costhawk@latest -- --self-test

You should see:

"hasApiKey": true
"autoSyncEnabled": true (if you enabled auto-sync)
"codexAutoSyncEnabled": true (unless intentionally disabled)
"local.codexDir": true when Codex sessions are discoverable

Then restart Claude Code and ask:

“What CostHawk tools are available?” “List my Codex sessions from the last 7 days”

Need Explicit Diagnostics?

Follow the MCP Operations Runbook for self-test interpretation, auto-sync checks, and Codex troubleshooting.

Alternative: —setup Command (All Platforms)

If you already have a token and want token mode directly:

npm exec --yes costhawk@latest -- --setup --api-key YOUR_TOKEN_HERE --auto-sync --codex-sync

Or configure manually with claude mcp add:

claude mcp add -s user -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE -e COSTHAWK_AUTO_SYNC=true costhawk -- npm exec --yes costhawk@latest

OpenCode (opencode.ai)

OpenCode reads MCP servers from ~/.config/opencode/opencode.json (or opencode.jsonc). Add CostHawk under mcp:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "costhawk": {
      "type": "local",
      "command": ["npx", "--yes", "costhawk@latest"],
      "enabled": true,
      "environment": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE"
      }
    }
  }
}

If you also use Claude Code or the OpenAI Codex CLI on this machine, you can enable local auto-sync by adding "COSTHAWK_AUTO_SYNC": "true" (and optionally "COSTHAWK_CODEX_AUTO_SYNC": "false" to disable Codex sync). Prefer a guided setup? Run:

npm exec --yes costhawk@latest -- --login --opencode --no-claude

Claude-Only Mode

If you want to sync Claude Code usage but not Codex CLI, add the extra env var:

macOS/Linux
Windows (manual)

claude mcp add -s user \
  -e COSTHAWK_API_KEY=YOUR_TOKEN_HERE \
  -e COSTHAWK_AUTO_SYNC=true \
  -e COSTHAWK_CODEX_AUTO_SYNC=false \
  costhawk -- npm exec --yes costhawk@latest

{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
        "COSTHAWK_AUTO_SYNC": "true",
        "COSTHAWK_CODEX_AUTO_SYNC": "false"
      }
    }
  }
}

Claude Desktop

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
        "COSTHAWK_AUTO_SYNC": "true"
      }
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "costhawk": {
      "command": "npx",
      "args": ["--yes", "costhawk@latest"],
      "env": {
        "COSTHAWK_API_KEY": "YOUR_TOKEN_HERE",
        "COSTHAWK_AUTO_SYNC": "true"
      }
    }
  }
}

Then restart Claude Desktop.

Updating

The MCP server uses costhawk@latest, which usually refreshes automatically after restart. To force refresh and verify the binary in use:

npm exec --yes costhawk@latest -- --self-test

If needed, clear the npx cache:

macOS/Linux
Windows

rm -rf ~/.npm/_npx

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"

Then restart Claude Code/Desktop.

Environment Variables

Variable	Required	Default	Description
`COSTHAWK_API_KEY`	Yes	-	Your CostHawk access token
`COSTHAWK_API_URL`	No	`https://costhawk.ai`	API base URL
`COSTHAWK_AUTO_SYNC`	No	`false`	Enable automatic sync on tool calls
`COSTHAWK_CODEX_AUTO_SYNC`	No	`true` when auto-sync is enabled	Include Codex CLI data in syncs
`COSTHAWK_CODEX_SESSIONS_DIR`	No	auto-discovery	Override Codex sessions directory if your setup is non-standard (useful when Codex install or `CODEX_HOME` changes paths)

Trust & Privacy Features

CostHawk is designed with transparency in mind. Here’s how to verify what the MCP server does:

Preview Mode (Dry Run)

Before syncing any data, you can preview exactly what would be sent:

"Sync my Claude Code usage with dryRun enabled"

This returns the full payload without making any network requests.

See What Files We Access

Run this command to see all files CostHawk would read:

npm exec --yes costhawk@latest -- --what-we-read

The command output lists detected directories and sample files read for local parsing.

What Data We Send

When you sync, CostHawk sends only:

Token counts - Input/output/cache tokens per session
Model identifiers - Which AI models were used
Timestamps - When sessions occurred
Hashed project IDs - For grouping (never actual project names or paths)
Calculated costs - Based on token counts and current pricing

We never send:

Your code or files
Prompt content or conversations
File paths or project names
Any personally identifiable information

​Quick Setup

​macOS / Linux

​Windows

​What Login Creates

​Verify Installation

Need Explicit Diagnostics?

​Alternative: —setup Command (All Platforms)

​OpenCode (opencode.ai)

​Claude-Only Mode

​Claude Desktop

​macOS

​Windows

​Updating

​Environment Variables

​Trust & Privacy Features

​Preview Mode (Dry Run)

​See What Files We Access

​What Data We Send

Quick Setup

macOS / Linux

Windows

What Login Creates

Verify Installation

Alternative: —setup Command (All Platforms)

OpenCode (opencode.ai)

Claude-Only Mode

Claude Desktop

macOS

Windows

Updating

Environment Variables

Trust & Privacy Features

Preview Mode (Dry Run)

See What Files We Access

What Data We Send