Claude Code Integration

The /tokage Skill

Automatic LLM cost observability for every Claude Code session. Install once, and token usage from every AI response is metered, cost-attributed, and available in your team dashboard.

What IS tracked

+ Model name (e.g., claude-sonnet-4-6)
+ Input and output token counts
+ Session ID
+ Your user ID (email/username)
+ Stop reason (end_turn, tool_use, etc.)

What is NEVER tracked

- Prompt content
- Code or file contents
- File paths
- Tool outputs or results
- Any response text

Employee Quick Install (~30 seconds)

Step 1 — Run the installer:

shell

curl -fsSL https://tokage.dev/install.sh | bash

Step 2 — Open Claude Code and run the onboarding skill:

shell

/(tokage)

The skill will ask for your API key and email, validate against the live API, and write ~/.config/tokage/config.json.

After setup, the hook fires automatically after each Claude Code response and sends token usage to Tokage. No further action needed.

How It Works

The skill installs a Claude Code Stop hook — a small Node.js script (tokage-hook.mjs) that fires after every AI response. The hook reads usage metadata from the Claude Code environment and posts it to the Tokage ingestion API.

flow

Claude Code response ends

↓

Stop hook fires: node ~/.config/tokage/hook.mjs stop

↓

Reads token counts from hook context

↓

Posts to POST /api/v1/events/batch

↓

Event appears in dashboard within seconds

Event Payload

Each hook invocation posts a single JSON event. Cost fields are absent — cost is stamped server-side by the Price Registry.

json

{
  "schema_version": 1,
  "model_provider": "anthropic",
  "model_id": "claude-sonnet-4-6",
  "input_tokens": 1234,
  "output_tokens": 567,
  "timestamp_client": "2026-02-24T10:30:00.000Z",
  "application_id": "claude-code",
  "user_id": "alice@company.com",
  "team_id": "engineering",
  "environment": "production",
  "metadata": {
    "session_id": "abc123",
    "stop_reason": "end_turn",
    "cache_creation_tokens": "0",
    "cache_read_tokens": "0"
  }
}

Config File Reference

User config (~/.config/tokage/config.json)

json

// ~/.config/tokage/config.json
{
  "schema_version": 1,
  "api_key": "tok_live_<32 chars>",
  "user_id": "alice@company.com",
  "application_id": "claude-code",
  "team_id": "engineering",
  "environment": "production",
  "ingest_url": "https://tokage.dev/api/v1"
}

Project config (.tokage.json in project root)

json

// .tokage.json (in project root — checked into version control)
{
  "team_id": "frontend",
  "application_id": "my-project",
  "metadata": {
    "project": "web-app",
    "phase": "dev"
  }
}
// Overrides global config for this project. Env vars override both.

Place a .tokage.json in your project root to set project-specific defaults. The hook walks up from the working directory to find it. Project values override global config; environment variables override both.

IT-managed company config (~/.config/tokage/company.json)

json

// ~/.config/tokage/company.json (IT-managed, mode 0444)
{
  "api_key": "tok_live_YOUR_COMPANY_KEY",
  "ingest_url": "https://tokage.dev/api/v1",
  "application_id": "claude-code",
  "team_id": "engineering"
}

When company.json is present, the API key from it is used and employees are never prompted for a key during onboarding.

Offline Behavior

If the ingestion API is unreachable, the hook appends events to ~/.config/tokage/queue.jsonl. On the next successful run, up to 20 queued events are replayed and removed from the queue. No events are lost as long as the machine eventually regains network access.

Manual Hook Registration

If the one-line installer is unavailable, copy tokage-hook.mjs to ~/.config/tokage/hook.mjs manually and add this to ~/.claude/settings.json:

json

// Add to ~/.claude/settings.json (merge, do not overwrite)
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.config/tokage/hook.mjs stop"
          }
        ]
      }
    ]
  }
}

Verify Connectivity

shell

curl -sf -o /dev/null -w "%{http_code}" \
  -X POST \
  -H "X-API-Key: $(jq -r .api_key ~/.config/tokage/config.json)" \
  -H "Content-Type: application/json" \
  -d '{"events":[]}' \
  https://tokage.dev/api/v1/events/batch
# Expected: 400 (empty batch rejected — key is valid and server is reachable)

IT Admin: Pre-provisioning Employees

Push company.json via MDM (Jamf, Kandji, Mosyle) to all developer machines before employees run the installer. Employees will never be prompted for an API key.

yaml

# Example Jamf/Kandji/Mosyle payload
destination: ~/.config/tokage/company.json
permissions: 0444
content: |
  {
    "api_key": "tok_live_YOUR_COMPANY_KEY_HERE",
    "ingest_url": "https://tokage.dev/api/v1",
    "application_id": "claude-code",
    "team_id": "engineering"
  }

Then distribute the one-liner to employees via Slack, email, or your IT portal:

shell

curl -fsSL https://tokage.dev/install.sh | bash

Troubleshooting

Hook not firing

Check that ~/.claude/settings.json contains a Stop hook entry with command: "node ~/.config/tokage/hook.mjs stop". Re-run the installer or add it manually.

401 from ingestion API

Your API key is invalid or inactive. Re-run /(tokage) to re-enter your key.

Events not appearing in the dashboard

Check the queue file: cat ~/.config/tokage/queue.jsonl. If it is growing, there is a persistent network or auth issue. Run the verification command above.

Node version too old

The hook requires Node.js 18+ (uses built-in fetch and ES modules). Run: node --version to check. Node 22 is recommended.

REST API Reference Back to Docs