Metadata-Version: 2.4
Name: cc-guardian
Version: 0.0.4
Summary: Security gateway for Claude Code traffic
Project-URL: Homepage, https://github.com/kunyuan/cc-guard
Author: Kun Yuan
License-Expression: MIT
Keywords: anthropic,claude,claude-code,proxy,sidecar
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx>=0.25
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9.0
Provides-Extra: sidecar
Requires-Dist: flowlens; extra == 'sidecar'
Requires-Dist: psutil>=5.9; (sys_platform == 'win32') and extra == 'sidecar'
Description-Content-Type: text/markdown

# cc-guard

Security gateway for Claude Code traffic.

> **Not to be confused with** [`agent-guard`](https://github.com/kunyuan/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.

```bash
# 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`.

```bash
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`](docs/execution-logic.md) for the wire flow.

## License

MIT
