# TokenGuard

**Stop Claude Code from wasting your tokens and making dangerous mistakes.**

Claude Code is powerful, but out of the box it has no guardrails. It will read thousands of lines from `node_modules`, accidentally commit your `.env` file, force-push to main, and burn through your entire context window without warning.

TokenGuard fixes this. It installs 11 safety gates that check every single action Claude Code takes before it happens. Bad action? Blocked. Good action? Passes through instantly.

```bash
pip install tokenguard
cd your-project
tokenguard init
```

That's it. Your project is now protected.

## What does it actually do?

Every time Claude Code tries to use a tool (read a file, run a command, write code), TokenGuard checks the action against 11 rules:

| Gate | What it prevents |
|------|-----------------|
| **Dependency Guardian** | Reading `node_modules`, `venv`, `dist`, `__pycache__` -- folders that burn thousands of tokens for zero value |
| **Destructive Git** | Force push, `reset --hard`, `clean -fd`, `stash drop` -- actions that destroy your work |
| **Git Push Gate** | Pushes to protected branches (`main`, `master`, `develop`, `release`, `production`) |
| **Secrets Detection** | Committing `.env`, `.pem`, `credentials.json`, API keys, SSH keys |
| **Tool Substitution** | Using `grep` instead of `rg`, `find` instead of `fd`, `cat` pipes instead of Read -- slower tools that waste tokens |
| **Bash Linting** | Common shell syntax errors (semicolons after `$()`, broken `sed`, bad `[[ ]]` negation) |
| **Temp Script** | Creating throwaway scripts in `/tmp` that clutter your workflow |
| **Env Var Protection** | Reading sensitive environment variables (`$API_KEY`, `$SECRET`, `$TOKEN`, `$AWS_*`) |
| **Network Binding** | Binding to `0.0.0.0` without authentication -- exposing services to the network |
| **Context Gate** | Warns at 70% context usage, blocks at 85% -- prevents Claude from losing its memory mid-task |

If a gate blocks an action, Claude Code sees a clear message explaining why and what to do instead.

## Install

```bash
pip install tokenguard
```

Requires Python 3.9+. One dependency: Jinja2 (for template rendering). The generated hook uses Python stdlib only.

## Quick Start

```bash
cd your-project
tokenguard init
```

TokenGuard detects your project type automatically and generates a `.claude/` directory:

```
your-project/.claude/
  CLAUDE.md              # Project instructions tuned to your stack
  hooks/mirror-hook.py   # The 11 safety gates
  rules/                 # Efficiency and safety rules
  memory/MEMORY.md       # Persistent memory across sessions
  settings.json          # Registers the hook with Claude Code
```

### What is `.claude/`?

Claude Code reads a `.claude/` directory in your project for configuration. TokenGuard generates this directory with best-practice defaults so you don't have to write it yourself.

## Commands

| Command | What it does |
|---------|-------------|
| `tokenguard init` | Set up safety gates in your project |
| `tokenguard init --type rust` | Override auto-detected project type |
| `tokenguard init --dry-run` | Preview what would be created (no files written) |
| `tokenguard init --no-hooks` | Skip hook installation (rules and memory only) |
| `tokenguard update` | Check for available template updates |
| `tokenguard update --force` | Apply updates (your customizations are preserved) |
| `tokenguard status` | Show what's installed and whether updates are available |
| `tokenguard eject` | Remove TokenGuard tracking but keep all generated files |

## Project Detection

TokenGuard looks at your project files to determine the stack and generates tailored instructions:

| Files found | Detected as |
|-------------|-------------|
| `pyproject.toml`, `setup.py`, `requirements.txt` | Python |
| `package.json` | JavaScript |
| `Cargo.toml` | Rust |
| `go.mod` | Go |
| None of the above | Generic |

Override with `--type`:

```bash
tokenguard init --type javascript
```

## How Updates Work

When TokenGuard releases improved templates, `tokenguard update` compares your files:

- **Updatable** -- you haven't edited the file, and a newer template is available. Safe to update.
- **User-modified** -- you customized the file. TokenGuard will never overwrite your changes.
- **Current** -- already up to date.

```bash
tokenguard update          # See what changed
tokenguard update --force  # Apply the updates
```

## Ejecting

Want to keep the generated files but stop using TokenGuard?

```bash
tokenguard eject
```

This removes the `.tokenguard.json` tracking file and unregisters the hook. All your `.claude/` files stay exactly as they are -- fully yours to edit.

## How It Works Under the Hood

1. `tokenguard init` generates files from Jinja2 templates based on your project type
2. It registers a [PreToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks) in `.claude/settings.json`
3. On every Claude Code tool call, `mirror-hook.py` receives the action as JSON via stdin
4. It evaluates each gate in priority order and returns `allow` or `deny`
5. File hashes are stored in `.tokenguard.json` so updates know what you've changed

The hook is a single Python file using only the standard library. No background processes, no network calls, no dependencies.

## GRIP Users

If you already use GRIP globally, TokenGuard detects this and skips hook installation to avoid double-gating. You still get the project-level CLAUDE.md, rules, and memory scaffold.

Force full installation with:

```bash
tokenguard init --standalone
```

## Cross-Platform

TokenGuard works on Windows, macOS, and Linux. The hook handles platform differences (like `fcntl` on Unix vs `msvcrt` on Windows) automatically.

## TokenGuard vs GRIP

TokenGuard is the free, open-source foundation. It comes from **GRIP**, a full AI agent management system built by [ENTER Konsult](https://enterkonsult.com) for professional development teams.

| Capability | TokenGuard (free) | GRIP (full) |
|------------|:-:|:-:|
| 11 safety gates | Yes | Yes |
| Efficiency rules | Yes | Yes |
| Session memory scaffold | Yes | Yes |
| Project-aware CLAUDE.md | Yes | Yes |
| 100+ specialized skills | -- | Yes |
| 19 autonomous agents | -- | Yes |
| 26 operating modes (code, review, security, strategy...) | -- | Yes |
| Recursive self-improvement loops | -- | Yes |
| Adaptive context extension (1M tokens) | -- | Yes |
| Multi-session state persistence | -- | Yes |
| Team coordination and pair programming | -- | Yes |
| Sprint automation (issue to PR) | -- | Yes |
| PR review automation | -- | Yes |
| Custom skill and agent creation | -- | Yes |

If your team needs more than guardrails -- autonomous workflows, intelligent code review, multi-agent coordination, or custom AI tooling -- reach out to us.

**Website**: [enterkonsult.com](https://enterkonsult.com)

## License

MIT
