cc-guardian 0.0.4

Security gateway for Claude Code traffic

cc-guard

Security gateway for Claude Code traffic.

Not to be confused with agent-guard — that's a runtime security engine for AI agents. This is a config installer.

What it does

Point Claude Code at any local anthropic-compatible proxy (flowlens sidecar, litellm, mitmproxy, anthropic-proxy, …) by modifying ~/.claude/settings.json, and back it out cleanly when you're done. Optionally, spawn and supervise the proxy subprocess for you.

# A. Bring your own proxy — cc-guard just patches settings.json
flow run -c ~/.flowlens/sidecar.yaml &
cc-guard install http://127.0.0.1:9999
# ...
cc-guard uninstall

# B. Let cc-guard generate the sidecar config AND spawn the process
cc-guard install http://127.0.0.1:9999 --sidecar
# or against a remote flowlens hub for centralized audit:
cc-guard install http://127.0.0.1:9999 \
  --hub https://hub.example.com --hub-token $TOKEN

Your ANTHROPIC_API_KEY / ANTHROPIC_AUTH_TOKEN are passed through untouched in both modes — cc-guard never reads, stores, or rewrites credentials.

Why not just edit ~/.claude/settings.json by hand

Several things need to happen together for the redirect to actually stick:

• Back up the original ANTHROPIC_BASE_URL so uninstall can restore it (otherwise you lose whatever was there before).
• Clean conflicting export ANTHROPIC_BASE_URL=... lines in your shell rc file, since shell env vars override settings.json.
• Atomic writes so a Ctrl-C mid-edit doesn't corrupt your settings.
• Idempotent install/uninstall so running it twice doesn't double-backup or crash.

cc-guard does all of this, and provides doctor and status commands for checking things after the fact.

Design principles

1. Proxy-agnostic — any anthropic-compatible local proxy works; nothing is hard-coded to one implementation.
2. Never touches credentials — ANTHROPIC_AUTH_TOKEN and ANTHROPIC_API_KEY pass through unchanged. The proxy forwards them to the real upstream.
3. Clean uninstall — every change is backed up before it's made, and the optional managed sidecar is SIGTERM'd cleanly on uninstall.
4. Idempotent — repeat install/uninstall safely.
5. Plain installer by default — sidecar spawning is strictly opt-in via --sidecar / --hub / --sidecar-config. No background processes unless you asked.

Install

The PyPI package is cc-guardian (the short cc-guard name was too close to an unrelated ccguard project, so PyPI forced a rename). The CLI command is still cc-guard.

uv tool install cc-guardian
# or, to also get managed-sidecar support (pulls flowlens + psutil on Windows):
uv tool install "cc-guardian[sidecar]"
# or
pipx install cc-guardian
# or
pip install --user cc-guardian

Two commands are installed: cc-guard (full name) and ccg (short alias).

Platforms: Linux, macOS, Windows. The plain installer is fully cross-platform; the managed sidecar uses start_new_session on POSIX and DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP on Windows. Shell rc cleanup is POSIX-only (no equivalent concept in cmd.exe / PowerShell).

Commands

Command	Purpose
cc-guard install URL	Point Claude Code at URL (plain mode)
cc-guard install URL --sidecar	+ spawn a local flowlens sidecar
cc-guard install URL --hub HUB --hub-token TOK	+ attach to a remote hub
cc-guard uninstall	Restore previous settings, stop managed sidecar
cc-guard status	Show current install state + sidecar liveness
cc-guard doctor	Run diagnostic checks
cc-guard (no args)	Interactive wizard

See cc-guard <command> --help for all options, or read docs/execution-logic.md for the wire flow.

License

MIT