tokenguard 0.4.0

Safety gates, efficiency rules, and persistent memory for Claude Code projects

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.

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

pip install tokenguard

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

Quick Start

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:

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.

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

Ejecting

Want to keep the generated files but stop using TokenGuard?

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 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:

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 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

License

MIT