Install Halton Meter

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, Google Gemini, xAI). 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
• One of:
  • uv (recommended — brings its own Python interpreter, no system Python required), or
  • pipx with system Python 3.11, 3.12, 3.13, or 3.14, or
  • pip in a virtual environment
• Admin password access — needed once, for CA cert trust

Install

uvx runs the latest published wheel in an ephemeral environment — no install step, no Python prerequisite, every invocation fetches the current release:

uvx halton-meter init --apps

For a persistent CLI on PATH (recommended once you’ve decided to keep it):

uv tool install halton-meter

pipx is still fully supported:

pipx install halton-meter

After installation, confirm the CLI is on your PATH:

halton-meter --version

Choosing an install mode

Halton Meter has three install modes. Pick the one that fits your workflow before running init.

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 --full

Step-by-step: first install

1. Install the package

Pick one. All three install the same wheel from PyPI.

$ uvx halton-meter --version           # first run downloads the wheel
halton-meter 0.2.11

$ uv tool install halton-meter
✓ installed halton-meter v0.2.11

$ pipx install halton-meter
✓ installed halton-meter 0.2.11

2. 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 status

Expected output: HEALTHY with all rows green. If any row is amber or red:

halton-meter doctor

doctor prints every diagnostic signal with a concrete next-action for each failure. As of v0.2.8, the cloud-sync states are classified strictly — see Troubleshooting for the paused_unauthorised vs paused_forbidden decision tree.

4. Test a capture

Open a new terminal (so the updated shell rc is sourced) and run any real prompt:

halton-meter run claude --help

Then check the report:

$ halton-meter report

halton-meter v0.2.11 · cost report · 2026-05-24 12:23 UTC → 2026-05-24 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.

Reinstall, upgrade, or switch install channels

halton-meter init is fully idempotent and reconciles state — you do not need to uninstall first to switch install channels or upgrade. The cert, SQLite store, and config all survive.

# Whichever channel you installed with — pick one:
$ uv cache clean halton-meter && uvx halton-meter --version    # uvx (force latest)
$ uv tool upgrade halton-meter                                 # uv tool
$ pipx upgrade halton-meter                                    # pipx

# Re-run init so the launchd plists point at the new binary path:
$ halton-meter init --apps

If the binary or its venv is in a weird state — a partial install, a corrupt certifi marker, or a stale pre-v0.2.x layout — reinstall cleanly:

$ pipx reinstall halton-meter                # or:
$ uv tool install --force halton-meter       # uv tool path
# uvx has no "reinstall" — uv cache clean forces a fresh fetch:
$ uv cache clean halton-meter && uvx halton-meter --version

$ halton-meter init --apps

For a complete uninstall — removing the supervisor, restoring the macOS proxy state from snapshot, and optionally purging captured data — see halton-meter uninstall.

What’s next

1. First request — verify captures are working, understand daily usage in each mode, and learn how to switch modes without uninstalling.
2. Troubleshooting — diagnoses and fixes for every known failure mode: cert errors, daemon loops, missing captures, paused_unauthorised, loopback-bind exit, and more.
3. Connect to Cloud — pair this daemon to a team workspace later (entirely opt-in; nothing flows until you approve in the browser).

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.