Halton Meter is a local network proxy that sits between your LLM clients
(Claude Code, Cursor, the Anthropic SDK, etc.) and the LLM provider APIs
(Anthropic, OpenAI, etc.). It intercepts HTTPS calls to provider endpoints
via a local mitmproxy instance, parses request and response bodies to extract
model name, token counts, and cost, and logs each request to a local SQLite
database at ~/.halton-meter/db.sqlite. It never modifies your code or wraps
SDKs. If the proxy fails, traffic falls through directly to the provider — your
tools keep working. Nothing about your development workflow changes.
Requirements
- macOS 12 (Monterey) or later. Linux is public beta (v0.1.24) and Windows is apps-mode beta (v0.2.x).
- Python 3.11, 3.12, 3.13, or 3.14 — all supported. (If you install with
uvxoruv tool install, uv provisions a matching interpreter for you.) pipx(recommended) orpip- Admin password access — needed once, for CA cert trust
Install
pipx install halton-meterOr with uvx for a one-shot run without a permanent install:
uvx halton-meter initOr directly with pip (virtual environment recommended):
pip install halton-meterAfter installation, confirm the CLI is on your PATH:
halton-meter --versionChoosing an install mode
Halton Meter has three install modes. Pick the one that fits your workflow
before running init.
| Mode | Command | What is set up | What gets metered | Can it break browsing? |
|---|---|---|---|---|
| env-only (default) | halton-meter init | CA cert + daemon + launchd supervisor only. Shell rc and launchctl env are untouched. | Only commands you route explicitly via halton-meter run <cmd> | No — system proxy is untouched |
| apps | halton-meter init --apps | Above + writes all env vars into your shell rc (.zshrc/.bashrc) + sets them in launchctl user domain so Spotlight/Dock-spawned apps inherit them | New terminals, Windsurf, Cursor, VS Code, Claude Desktop, JetBrains IDEs (any Spotlight/Dock-launched app that respects HTTPS_PROXY env) | No — system proxy is untouched |
| full | halton-meter init --full | All of --apps + enables the macOS system proxy | Browsers, GUI apps that ignore HTTPS_PROXY env, all HTTPS traffic | Yes — Chrome/Safari may break on HSTS sites if cert trust is incomplete |
If you’re unsure, start with --apps. It covers the common IDE use case
(Windsurf, Cursor, VS Code with Claude extensions) without touching the system
proxy, so it cannot break HTTPS in your browser.
"I just want to meter my Claude Code / SDK calls from the terminal."
→ halton-meter init (env-only, default)
"I want Windsurf / Cursor / JetBrains to be metered when I open them
from Spotlight or the Dock, without risking browser breakage."
→ halton-meter init --apps
"I want to capture everything including browser traffic and I understand
the cert trust requirement."
→ halton-meter init --fullStep-by-step: first install
1. Install the package
pipx install halton-meter2. Run init with your chosen mode
The example below uses --apps (recommended for most users). Substitute
--full or omit the flag for env-only if that better fits your workflow.
$ halton-meter init --apps
1/8 Generating mitmproxy CA certificate…
✓ cert written ~/.mitmproxy/mitmproxy-ca-cert.pem
2/8 Trusting cert in macOS Keychain (admin password required)…
── macOS dialog appears — type your password and click OK ──
✓ keychain trusted
3/8 Patching certifi bundle so Python clients trust the cert…
✓ certifi patched
4/8 Installing launchd plist for daemon auto-start…
✓ launchd registered com.haltonlabs.meter
5/8 Writing env vars to shell rc and launchctl user domain…
✓ shell rc updated ~/.zshrc
✓ launchctl env set HTTPS_PROXY HTTP_PROXY NO_PROXY SSL_CERT_FILE …
6/8 (skipped — system proxy unchanged in --apps mode)
7/8 Starting daemon and running self-test (up to 30 s)…
✓ daemon healthy edge: 127.0.0.1:8081 api: 127.0.0.1:8765
8/8 Done.
✓ init complete mode: apps
During init, a macOS password dialog appears at step 2. This is expected — the CA cert must be added to your system Keychain under admin authority. Type your password and click OK.
3. Verify the install
halton-meter statusExpected output: HEALTHY with all rows green. If any row is amber or red:
halton-meter doctordoctor prints every diagnostic signal with a concrete next-action for each
failure.
4. Test a capture
Open a new terminal (so the updated shell rc is sourced) and run any real prompt:
halton-meter run claude --helpThen check the report:
$ halton-meter report
halton-meter v0.1.5 · cost report · 2026-04-30 12:23 UTC → 2026-04-30 13:59 UTC
✓ 667 requests across 4 projects · 3 models
✓ Tokens: 92,522 in · 399,359 out
✓ Total cost: $47.532030
by project requests in out cost avg latency
────────────────────────────────────────────────────────────────────────────────
AlgoNifty 168 28,807 91,725 $7.552180 9,166ms
IntelStackWeb 126 4,206 98,880 $10.370110 13,546ms
halton-meter 348 45,396 188,781 $29.066200 10,768ms
halton-meter-landing 25 14,113 19,973 $0.543540 15,923ms
by model requests in out cost
────────────────────────────────────────────────────────────────
claude-haiku-4-5-20251001 56 4,814 11,871 $0.249820
claude-opus-4-7 463 58,722 324,257 $43.460200
claude-sonnet-4-6 148 28,986 63,231 $3.822010
$ █If you see “No captures yet” instead, check the troubleshooting guide.
What’s next
- First request — verify captures are working, understand daily usage in each mode, and learn how to switch modes without uninstalling.
- Troubleshooting — diagnoses and fixes for every known failure mode: cert errors, daemon loops, missing captures, and more.
If you’re stuck for more than five minutes, that’s a docs bug. Email operator@haltonlabs.com and we’ll fix the page, not just answer the question.