cc-guard

Token usage estimator proxy for Claude Code — see costs before they happen

---

The problem

When you run an agentic coding tool like Claude Code, the actual tokens sent to the API far exceed what you typed. Each request includes the full system prompt, all tool definitions, file contents, conversation history, and more. You often don't know how many tokens were consumed until after the fact — and by then, the bill is already running.

The solution

cc-guard sits between Claude Code and the Anthropic API as a local HTTP proxy. Before forwarding each request, it calls Anthropic's /v1/messages/count_tokens endpoint to get an exact token count — this endpoint is free and does not consume your quota. The count is displayed in your terminal, and if it exceeds a configurable threshold, you get a confirmation prompt before the request goes through.

┌─ cc-guard ──────────────────────────────────────
│ Input tokens : 42,318
│ Est. cost    : $0.00013
│ Model        : claude-sonnet-4-5
│ Session      : call #3 | total 128,420 tokens
└─────────────────────────────────────────────────

---

Install

npm install -g cc-guard

Requires Node.js ≥ 18.

---

Quick start

Option 1 — Recommended: cc-guard run

Starts the proxy, injects ANTHROPIC_BASE_URL automatically, and shows a session summary when you exit:

cc-guard run -- claude

Option 2 — Manual background proxy

cc-guard start
export ANTHROPIC_BASE_URL=http://localhost:4999
claude

When done:

cc-guard stop

---

Configuration

Run the interactive configurator:

cc-guard config

Or edit ~/.cc-guard.json directly:

{
  "port": 4999,
  "threshold": 50000,
  "gate": true,
  "showCostEstimate": true,
  "pricing": {}
}

Field	Default	Description
port	4999	Local proxy port
threshold	50000	Token count above which the gate prompt appears
gate	true	Enable/disable the confirmation prompt
showCostEstimate	true	Show estimated USD cost alongside token count
pricing	{}	Override per-model pricing (USD per million tokens)

---

How it works

Claude Code
    │
    │  POST /v1/messages
    ▼
cc-guard (localhost:4999)
    │
    ├─► count_tokens API ──► token count (free, no quota)
    │        │
    │   display in terminal
    │   (gate if over threshold)
    │
    └─► api.anthropic.com  ──► streaming response
              │
              ▼
         Claude Code
              │
              ▼
       session summary on exit

1. Claude Code sends a request to localhost:4999 instead of api.anthropic.com
2. cc-guard reads the body and calls count_tokens to get an exact input token count
3. The count (and estimated cost) is printed to your terminal
4. If the count exceeds your threshold and gate: true, you are prompted to confirm
5. On confirmation, the request is forwarded to api.anthropic.com and the streaming response is piped back in real time
6. Actual token usage is parsed from the SSE stream and accumulated in the session

---

Commands

Command	Description
cc-guard start	Start proxy in the background
cc-guard stop	Stop the background proxy
cc-guard status	Show proxy status, port, threshold, config path
cc-guard run -- <cmd>	Start proxy + run command with env var injected
cc-guard config	Interactive config editor
cc-guard init	Create default ~/.cc-guard.json

---

FAQ

Q: Does the count_tokens call consume my API quota? A: No. Anthropic's /v1/messages/count_tokens endpoint is free and does not count against your rate limits or usage quota.

Q: Does cc-guard slow down Claude Code's responses? A: The count_tokens call typically takes 100–200 ms. Streaming responses are piped through in real time with no additional buffering, so there's no latency added to the actual generation.

Q: Does cc-guard store my API key? A: No. The API key is read from the incoming request header and passed straight through. It is never written to disk.

Q: Does it support OpenAI, Gemini, or other providers? A: Not yet. cc-guard is currently Anthropic-specific. Support for other providers is planned.

Q: What if count_tokens fails? A: cc-guard will log a warning and forward the request anyway. It never blocks your request due to a counting error.

---

License

MIT