tokenguard 0.2.0__tar.gz

tokenguard-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.pytest_cache/

tokenguard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ENTER Konsult
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenguard-0.2.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: tokenguard
+Version: 0.2.0
+Summary: Safety gates, efficiency rules, and persistent memory for Claude Code projects
+Project-URL: Homepage, https://enterkonsult.com
+Project-URL: PyPI, https://pypi.org/project/tokenguard/
+Author: ENTER Konsult
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,claude,claude-code,gates,guardrails,safety,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Requires-Dist: jinja2>=3.0
+Provides-Extra: test
+Requires-Dist: pytest-tmp-files>=0.0.2; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 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

tokenguard-0.2.0/README.md

@@ -0,0 +1,171 @@
+# 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

tokenguard-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tokenguard"
+version = "0.2.0"
+description = "Safety gates, efficiency rules, and persistent memory for Claude Code projects"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [
+    { name = "ENTER Konsult" },
+]
+keywords = ["claude", "claude-code", "safety", "gates", "ai", "tokens", "guardrails"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Quality Assurance",
+]
+
+dependencies = [
+    "jinja2>=3.0",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=7.0",
+    "pytest-tmp-files>=0.0.2",
+]
+
+[project.scripts]
+tokenguard = "tokenguard.cli:main"
+
+[project.urls]
+Homepage = "https://enterkonsult.com"
+PyPI = "https://pypi.org/project/tokenguard/"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tokenguard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

tokenguard-0.2.0/tests/test_detector.py

@@ -0,0 +1,142 @@
+"""Tests for project type detection."""
+
+import json
+from pathlib import Path
+
+from tokenguard.detector import (
+    detect_existing_hooks,
+    detect_existing_mirror,
+    detect_project_type,
+    has_grip_hook,
+)
+
+
+def test_detect_python_pyproject(tmp_path):
+    (tmp_path / "pyproject.toml").write_text("[project]\nname = 'test'\n")
+    assert detect_project_type(tmp_path) == "python"
+
+
+def test_detect_python_requirements(tmp_path):
+    (tmp_path / "requirements.txt").write_text("flask\n")
+    assert detect_project_type(tmp_path) == "python"
+
+
+def test_detect_javascript(tmp_path):
+    (tmp_path / "package.json").write_text('{"name": "test"}\n')
+    assert detect_project_type(tmp_path) == "javascript"
+
+
+def test_detect_rust(tmp_path):
+    (tmp_path / "Cargo.toml").write_text("[package]\nname = 'test'\n")
+    assert detect_project_type(tmp_path) == "rust"
+
+
+def test_detect_go(tmp_path):
+    (tmp_path / "go.mod").write_text("module test\n")
+    assert detect_project_type(tmp_path) == "go"
+
+
+def test_detect_generic_empty(tmp_path):
+    assert detect_project_type(tmp_path) == "generic"
+
+
+def test_detect_generic_makefile_only(tmp_path):
+    (tmp_path / "Makefile").write_text("all:\n\techo hi\n")
+    assert detect_project_type(tmp_path) == "generic"
+
+
+def test_python_takes_priority_over_makefile(tmp_path):
+    (tmp_path / "pyproject.toml").write_text("[project]\n")
+    (tmp_path / "Makefile").write_text("all:\n")
+    assert detect_project_type(tmp_path) == "python"
+
+
+def test_detect_existing_mirror_not_present(tmp_path):
+    assert detect_existing_mirror(tmp_path) is None
+
+
+def test_detect_existing_mirror_present(tmp_path):
+    claude_dir = tmp_path / ".claude"
+    claude_dir.mkdir()
+    data = {"version": "0.1.0", "project_type": "python"}
+    (claude_dir / ".tokenguard.json").write_text(json.dumps(data))
+    result = detect_existing_mirror(tmp_path)
+    assert result is not None
+    assert result["version"] == "0.1.0"
+
+
+def test_detect_existing_mirror_corrupt_json(tmp_path):
+    claude_dir = tmp_path / ".claude"
+    claude_dir.mkdir()
+    (claude_dir / ".tokenguard.json").write_text("not json")
+    assert detect_existing_mirror(tmp_path) is None
+
+
+# =========================================================================
+# Hook detection (GRIP coexistence)
+# =========================================================================
+
+def test_detect_existing_hooks_empty(tmp_path):
+    """No settings.json -> no hooks."""
+    assert detect_existing_hooks(tmp_path) == []
+
+
+def test_detect_existing_hooks_from_project(tmp_path):
+    """Hooks in project settings.json should be detected."""
+    claude_dir = tmp_path / ".claude"
+    claude_dir.mkdir()
+    settings = {
+        "hooks": {
+            "PreToolUse": [{
+                "matcher": ".*",
+                "hooks": [{"type": "command", "command": "python3 hooks/my-hook.py"}]
+            }]
+        }
+    }
+    (claude_dir / "settings.json").write_text(json.dumps(settings))
+    hooks = detect_existing_hooks(tmp_path)
+    assert len(hooks) == 1
+    assert "my-hook.py" in hooks[0]
+
+
+def test_has_grip_hook_false(tmp_path):
+    """No GRIP hook -> False."""
+    assert has_grip_hook(tmp_path) is False
+
+
+def test_has_grip_hook_true(tmp_path):
+    """GRIP context-gate-hook.py registered -> True."""
+    claude_dir = tmp_path / ".claude"
+    claude_dir.mkdir()
+    settings = {
+        "hooks": {
+            "PreToolUse": [{
+                "matcher": ".*",
+                "hooks": [{
+                    "type": "command",
+                    "command": "python3 ~/.claude/hooks/context-gate-hook.py"
+                }]
+            }]
+        }
+    }
+    (claude_dir / "settings.json").write_text(json.dumps(settings))
+    assert has_grip_hook(tmp_path) is True
+
+
+def test_has_grip_hook_not_triggered_by_mirror(tmp_path):
+    """Mirror hook should not be detected as GRIP hook."""
+    claude_dir = tmp_path / ".claude"
+    claude_dir.mkdir()
+    settings = {
+        "hooks": {
+            "PreToolUse": [{
+                "matcher": ".*",
+                "hooks": [{
+                    "type": "command",
+                    "command": "python3 .claude/hooks/mirror-hook.py"
+                }]
+            }]
+        }
+    }
+    (claude_dir / "settings.json").write_text(json.dumps(settings))
+    assert has_grip_hook(tmp_path) is False