blackbar

A local proxy for Claude Code. It replaces confidential data with placeholders before a request leaves your machine, and puts the real values back in the reply.

Regexes catch emails, keys and IDs. A local LLM catches names, companies and addresses. Nothing is sent anywhere to be classified.

Install

Paste into Claude Code:

Install https://github.com/xtompie/blackbar for me

Agent reading this: fetch https://raw.githubusercontent.com/xtompie/blackbar/main/INSTALL.md and follow it from step 0. Do not skip the verification steps, and do not narrate them.

Use

blackbar claude

Claude Code behaves as usual. Your arguments (--resume, -c, -p) are passed through.

The model cannot answer questions about a value it never saw. Ask "is this ID number valid?" and it is looking at {{sensitive:pesel:1a33de}}. For that one session, run blackbar direct.

Commands

blackbar claude              # run Claude Code through the proxy
blackbar direct              # run it without the proxy, nothing redacted

blackbar start               # start the daemon
blackbar stop                # stop it, dropping open connections
blackbar restart             # both, with an empty vault afterwards
blackbar status              # what is covered and what has gone through
blackbar mode                # per command or always, and what holds it

blackbar watch               # follow the traffic live
blackbar watch --reveal      # ⚠ also print the values that were replaced
blackbar last -n 5           # the last few requests
blackbar stats --today       # totals per kind and layer
blackbar logs                # the daemon's own log

blackbar file notes.md notes.anon.md            # redact a file for use anywhere else
blackbar test "Jan Kowalski, jan@example.com"   # what would be replaced, and by which layer
blackbar rules add "Acme Ltd" --kind company    # add a pattern of your own
blackbar rules list|edit|reload

blackbar allow list          # file types sent through unredacted
blackbar allow add image/png # ⚠ sent as-is
blackbar allow remove image/png

blackbar service install     # keep the daemon alive across reboots and crashes
blackbar attach              # route every `claude` through the proxy, not just this command
blackbar detach              # undo that

blackbar model list|pull|status
blackbar vault status|show|clear
blackbar config get|set|edit
blackbar doctor              # check the setup
blackbar update              # pull and reinstall
blackbar uninstall

Two ways to run it

Per command (default). Only blackbar claude goes through the proxy. A plain claude connects straight to Anthropic, exactly as before. Nothing outside ~/.config/blackbar/ is touched.

Always. blackbar attach writes the proxy address into ~/.claude/settings.json, so every claude goes through it — including the ones you start out of habit. Since nothing would then check whether the daemon is alive, attach requires blackbar service install first; a dead daemon means claude will not start at all. Use blackbar direct to bypass it once, blackbar detach to go back.

In both cases the daemon starts on demand and dies with your machine. blackbar service install puts it under launchd (macOS) or systemd (Linux) instead, so it comes back after a reboot or a crash. blackbar service uninstall reverts that.

There is no pause switch. An "off" you can forget about is worse than no protection.

How it works

The daemon is an HTTP server on 127.0.0.1:8555. blackbar claude points ANTHROPIC_BASE_URL at it and execs the real claude.

On the way out it scans system, message content and tool results. Tool results matter most: that is where file contents and command output end up. Tool definitions and signed thinking blocks are left alone.

The same value always gets the same placeholder, so prompt caching keeps working. The map lives in the daemon's memory and is never written to disk.

On the way back the placeholders become values again — including inside streamed responses, where one can arrive split across two network chunks, and inside tool call arguments, where it has to be re-escaped as JSON.

Attachments would otherwise travel as base64 and be parsed on Anthropic's side. Instead PDF, Word and anything textual are read locally, redacted, and sent as text; the layout is lost. What cannot be read — a screenshot, a scanned PDF — is refused unless you allow its type.

Only /v1/messages and /v1/messages/count_tokens are redacted. Any other POST is refused rather than forwarded unredacted.

The log

Two lines per exchange in ~/.local/state/blackbar/requests.log, sharing an id: phase=sent the moment the redacted request goes out, phase=back when the reply is done.

ts=1785592127.227 id=1 phase=sent session=c87238 model=claude-opus-5 stream=0
chars=132 masked=2 kinds=email:1,person:1 layers=gliner:1,regex:1
keys=person:719c22,email:89c66f detect_ms=260.5

ts=1785592127.510 id=1 phase=back session=c87238 status=401 restored=0 orphans=0
total_ms=543.2 cache_read=0 input_tokens=0

chars is how much text was handed to the scanner, which is what detect_ms was spent on - not the size of the request, which is mostly tool definitions we never read.

A slow request is visible while it is still running, and one that never came back stays a sent with no back. Several Claude Code windows can write at once - lines interleave, but a single line is written in one append, so none of them is ever mangled.

restored=0 is normal: it means the model did not repeat any placeholder. The number to watch is orphans - anything above zero came back mangled and could not be turned into a value again.

blackbar watch reads the same file:

16:53:59 #1 → email:1 372ms scanning 10 chars
16:53:59 #1 ← nothing to restore status 401 · 658ms
16:53:59 #2 refused: unhandled_endpoint POST:/v1/skills/sync
16:53:59 #3 refused: unhandled_endpoint PUT:/v1/memory_stores/abc

The file records what happened, never what was in it — the keys are hashes. watch --reveal resolves them against the running daemon; it and vault show are the only commands that print real data.

An empty log while a Claude Code window is running means that window is bypassing the proxy.

Where things live

~/.local/share/blackbar/repo    the clone `blackbar update` pulls
~/.local/share/blackbar/venv    the environment it runs from
~/.config/blackbar/             config.toml, rules.yaml
~/.local/state/blackbar/        requests.log, daemon.log

Limitations

• Starting the daemon takes ~15 s (loading the model) and large files are slow to scan: 100 KB costs about half a minute, once.
• The model cannot reason about values it never saw.
• It can also mangle a placeholder — asking it to translate the text does it reliably. The value stayed home, but the reply comes back with {{sensitive:...}} in it. Counted as orphans in blackbar stats.
• Restarting the daemon empties the vault. Open sessions keep working - Claude Code holds the real history and resends it, so it just gets fresh placeholders - but the prompt cache is lost. A placeholder that already reached a file on disk stays unresolvable.
• Changing your rules changes the prompt, so the next request misses the prompt cache.
• Remote Control does not work behind a proxy (Claude Code gates it to api.anthropic.com since v2.1.196).

License

MIT