First request on Linux

Verifying captures are working

Open a new terminal so the env vars from your ~/.bashrc / ~/.zshrc are sourced (Halton Meter does not modify your rc on Linux in v0.1.24 — you set them by hand during install). Then run a real LLM call:

claude --print "Reply with exactly: pong"

Then:

halton-meter report

A row appears for every intercepted LLM request. Columns include: timestamp, project, model, tokens in/out, cost.

If report is empty but halton-meter status shows the daemon and edge both green, walk this checklist in order:

1. echo $HTTPS_PROXY — should be http://127.0.0.1:8081. If empty, your rc edits didn’t apply to this shell. Open a new terminal.
2. echo $SSL_CERT_FILE — should point at the patched certifi bundle. Python LLM SDKs (Anthropic SDK, httpx, requests) won’t trust the mitmproxy cert without it.
3. echo $NODE_EXTRA_CA_CERTS — should be the same bundle. Claude Code and the Gemini CLI are Node binaries; they don’t read SSL_CERT_FILE.
4. The provider hostname matches a supported adapter. See providers. Off-list hostnames pass through without capture (intentional — observation never breaks the workflow).
5. The full failure-mode list with copy-paste fixes is in Troubleshooting → No captures.

Daily usage

In apps mode every new shell inherits HTTPS_PROXY etc. from your rc, so terminal-launched tools are metered without any wrapper command.

$ claude --print "ping"            # captured automatically
$ python my_script.py             # captured if it uses httpx / requests / Anthropic SDK
$ npx some-llm-tool              # captured via NODE_EXTRA_CA_CERTS + HTTPS_PROXY

halton-meter run still works in any mode if you want explicit, per-process metering — useful inside cron, systemd units, or any context that doesn’t inherit your interactive shell rc.

$ halton-meter run claude                              # meter Claude Code
$ halton-meter run python my_script.py                 # meter a python script
$ halton-meter run -- npx some-llm-tool --some-flag   # use -- so flags reach the inner cmd
$ halton-meter run --shell                              # interactive metered subshell

Extending metering to project venvs

The certifi patch only applies to the Python that pipx installed Halton Meter into. If your LLM script runs from a different venv (e.g. ~/projects/foo/.venv), point that interpreter’s SSL_CERT_FILE at the patched pipx bundle:

$ PATCHED=$(halton-meter run -- python3 -c "import certifi; print(certifi.where())")
$ echo "export SSL_CERT_FILE=$PATCHED" >> ~/projects/foo/.envrc
$ echo "export REQUESTS_CA_BUNDLE=$PATCHED" >> ~/projects/foo/.envrc

Or copy the same export lines you put in ~/.bashrc into the venv’s activate script.

Checking daemon health

$ halton-meter status            # quick health summary
$ halton-meter doctor            # full diagnostic with copy-paste fixes
$ systemctl --user is-active halton-meter.service halton-meter-edge.service
active
active

Starting and stopping

halton-meter start and stop proxy through systemctl --user. Stop only stops the daemon — the edge stays up so apps with HTTPS_PROXY already in their env continue to work in pure-passthrough mode. This is the cardinal rule: observation never breaks the workflow.

$ halton-meter start                              # start daemon via systemctl --user
$ halton-meter stop                               # stop daemon; edge keeps your apps connected
$ halton-meter stop && halton-meter start   # restart after config change

You can also drive systemd directly:

$ systemctl --user restart halton-meter.service
$ systemctl --user restart halton-meter-edge.service
$ systemctl --user reset-failed halton-meter.service halton-meter-edge.service  # clear StartLimitBurst counter

What’s next

• Configure projects — set per-project metering rules. The conceptual content is OS-agnostic.
• Troubleshooting — the Linux-specific failure-mode reference.
• Logs — where systemd-redirected output lives and how to read journalctl --user.