token-hunt 0.1.0__tar.gz

token_hunt-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-marketplace.json",
+  "name": "JordanNewell",
+  "owner": {
+    "name": "Jordan Newell",
+    "url": "https://jordannewell.com"
+  },
+  "plugins": [
+    {
+      "name": "token-hunt",
+      "source": "./plugin",
+      "description": "Catch secrets at chat time, not commit time. Hook-based scanner for Claude Code.",
+      "version": "0.1.0",
+      "category": "security",
+      "keywords": ["security", "secrets", "leak-prevention", "hooks"]
+    }
+  ]
+}

token_hunt-0.1.0/.gitattributes

@@ -0,0 +1,39 @@
+# Normalize line endings: LF in repo, LF in working copy.
+# Ends the "LF will be replaced by CRLF" warnings.
+* text=auto eol=lf
+
+# Explicit text types
+*.md   text eol=lf
+*.json text eol=lf
+*.js   text eol=lf
+*.ts   text eol=lf
+*.tsx  text eol=lf
+*.jsx  text eol=lf
+*.css  text eol=lf
+*.html text eol=lf
+*.yml  text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.sh   text eol=lf
+*.py   text eol=lf
+*.go   text eol=lf
+*.rs   text eol=lf
+*.txt  text eol=lf
+
+# Binaries — never touch
+*.png  binary
+*.jpg  binary
+*.jpeg binary
+*.gif  binary
+*.webp binary
+*.svg  text eol=lf
+*.ico  binary
+*.pdf  binary
+*.mp4  binary
+*.mov  binary
+*.mp3  binary
+*.wav  binary
+*.zip  binary
+*.gz   binary
+*.7z   binary
+

token_hunt-0.1.0/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+github: [JordanNewell]
+buy_me_a_coffee: jordannewell
+custom:
+  - "https://jordannewell.com/projects/token-hunt/"

token_hunt-0.1.0/.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,41 @@
+---
+name: Bug Report
+about: Report a false positive, false negative, or crash
+title: "[BUG] "
+labels: bug, triage
+---
+
+## Summary
+
+[One sentence describing the problem]
+
+## Repro
+
+```bash
+# Steps to reproduce
+```
+
+## Expected
+
+[What should have happened]
+
+## Actual
+
+[What actually happened]
+
+## Environment
+
+- token-hunt version: `token-hunt --version`
+- Python version:
+- OS:
+- Claude Code version (if plugin): 
+
+## Pattern that fired (or didn't)
+
+[kind, e.g. `zai-api-key`]
+
+## Output of `token-hunt list`
+
+```
+[paste here, redact fingerprints if real]
+```

token_hunt-0.1.0/.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,22 @@
+---
+name: Feature Request
+about: Suggest a new provider rule, detection class, or feature
+title: "[FEAT] "
+labels: enhancement, triage
+---
+
+## Summary
+
+[One sentence describing the request]
+
+## Use case
+
+[What problem does this solve? When does it come up?]
+
+## Proposed solution
+
+[Describe the approach. Code samples welcome.]
+
+## Alternatives considered
+
+[Any other ways to solve this — and why they don't work]

token_hunt-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Summary
+
+[One paragraph. What does this change do?]
+
+## Why
+
+[The motivation. Link any issues.]
+
+## Testing
+
+- [ ] Added tests for new behavior
+- [ ] All tests pass: `pytest`
+- [ ] Lint clean: `ruff check .`
+- [ ] Manually verified the change works as described
+
+## Checklist
+
+- [ ] No AI-attribution trailers in commit messages
+- [ ] No real secrets in test fixtures (use the fakes in `tests/fixtures.py`)
+- [ ] CHANGELOG updated if user-facing

token_hunt-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e402052b7b6f6d  # v5
+        with:
+          python-version: "3.12"
+      - run: pip install build twine
+      - run: python -m build
+      - uses: softprops/action-gh-release@da05d552573ad5aba039eaac05058a918a7bf631  # v2
+        with:
+          generate_release_notes: true
+      - run: twine upload dist/*
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

token_hunt-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,27 @@
+name: test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e402052b7b6f6d  # v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: pytest --cov=token_hunt --cov-report=xml
+      - uses: codecov/codecov-action@b9fd7d96f2d891b39a3e3a623df4d0ed71ef3841  # v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
+        with:
+          file: ./coverage.xml

token_hunt-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+dist/
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.venv/
+venv/
+env/
+.DS_Store
+.token-hunt/
+*.log
+!docs/**/*.md

token_hunt-0.1.0/.gitleaksignore

@@ -0,0 +1,45 @@
+# token-hunt test fixtures: shape-correct FAKE keys generated for
+# tests/test_builtin_providers.py — not real credentials. No real secrets
+# ship in this repo. Fingerprints below verified 2026-10-15.
+tests/__pycache__/test_builtin_providers.cpython-313-pytest-8.4.2.pyc:jwt:13
+tests/test_builtin_providers.py:generic-api-key:100
+tests/test_builtin_providers.py:generic-api-key:101
+tests/test_builtin_providers.py:generic-api-key:103
+tests/test_builtin_providers.py:generic-api-key:104
+tests/test_builtin_providers.py:generic-api-key:106
+tests/test_builtin_providers.py:generic-api-key:107
+tests/test_builtin_providers.py:generic-api-key:109
+tests/test_builtin_providers.py:generic-api-key:110
+tests/test_builtin_providers.py:generic-api-key:112
+tests/test_builtin_providers.py:generic-api-key:113
+tests/test_builtin_providers.py:generic-api-key:116
+tests/test_builtin_providers.py:generic-api-key:118
+tests/test_builtin_providers.py:generic-api-key:119
+tests/test_builtin_providers.py:generic-api-key:121
+tests/test_builtin_providers.py:generic-api-key:122
+tests/test_builtin_providers.py:generic-api-key:148
+tests/test_builtin_providers.py:generic-api-key:91
+tests/test_builtin_providers.py:generic-api-key:92
+tests/test_builtin_providers.py:generic-api-key:94
+tests/test_builtin_providers.py:generic-api-key:95
+tests/test_builtin_providers.py:generic-api-key:97
+tests/test_builtin_providers.py:generic-api-key:98
+tests/test_builtin_providers.py:generic-api-key:115
+tests/test_builtin_providers.py:generic-api-key:25
+tests/test_builtin_providers.py:generic-api-key:46
+tests/test_builtin_providers.py:generic-api-key:49
+tests/test_builtin_providers.py:generic-api-key:52
+tests/test_builtin_providers.py:generic-api-key:53
+tests/test_builtin_providers.py:generic-api-key:55
+tests/test_builtin_providers.py:generic-api-key:58
+tests/test_builtin_providers.py:generic-api-key:61
+tests/test_builtin_providers.py:generic-api-key:62
+tests/test_builtin_providers.py:generic-api-key:70
+tests/test_builtin_providers.py:generic-api-key:71
+tests/test_builtin_providers.py:generic-api-key:73
+tests/test_builtin_providers.py:generic-api-key:74
+tests/test_builtin_providers.py:generic-api-key:76
+tests/test_builtin_providers.py:generic-api-key:79
+tests/test_builtin_providers.py:generic-api-key:82
+tests/test_builtin_providers.py:generic-api-key:85
+tests/test_builtin_providers.py:jwt:88

token_hunt-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to token-hunt are documented here.
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Provider coverage expanded 12 → 37 rules for LLM-inference parity with the 53 providers Curtis ships: OpenRouter, Groq, Together, Fireworks, xAI, Perplexity, Hugging Face, Cerebras, Replicate, Vercel AI Gateway, NVIDIA NIM, Chutes, Requesty, Novita, Upstage, Baseten, Baidu Qianfan, fal.ai, Alibaba DashScope, Moonshot Kimi, Mistral, Cohere, Scaleway.
+- Generic fallback rules: unattributed `sk-` 32-char key (DeepSeek / StepFun / Moonshot / SiliconFlow / Poe / Qwen shape) and generic JWT (MiniMax / DeepInfra / Crusoe).
+- OpenAI rule tightened to the T3BlbkFJ marker shape — no longer double-fires with the generic `sk-` rule.
+- Prefixless shapes (Mistral, Cohere, Scaleway) and generic-prefix shapes (Novita, Upstage) are keyword-gated: the provider name must appear in the scanned text before the regex is tried.
+- Providers with no publicly documented key format get **keyword-gated opaque rules** (SambaNova, Nebius, AI21, OVHcloud, FriendliAI, GMI Cloud, Crusoe, Featherless, DeepInfra, Inference.net, BytePlus): provider name in text + 32+-char token. Low-precision by design — attribution + rotation URL, not shape confidence. Shape-verified rules stay provider-documented or multi-scanner-observed only; no guessed regexes.
+
+### Planned for v0.1.1
+- Silent redaction via `hookSpecificOutput.updatedToolOutput` for PostToolUse hooks (replaces current WARN-only behavior for Bash/Read/Write outputs)
+- Active verification mode (TruffleHog-style "is this key actually live?")
+- `--file-path` flag on `scan --stdin` to enable path-based allowlist for PostToolUse:Read
+
+## [0.1.0] — 2026-07-27
+
+### Added
+- Initial release.
+- Detection core: regex patterns (12 built-in providers), bash escape-hatch detector, entropy candidates.
+- Claude Code plugin with 6 hook scripts covering 8 detection rows.
+- CLI peer (`pip install token-hunt`) with `scan`, `list`, `close`, `watch` commands.
+- Pattern layering: builtin → `~/.token-hunt/patterns.local.toml` → `./.token-hunt/patterns.local.toml`.
+- Allowlist engine (path-based + fingerprint-based).
+- `rotations.log` JSONL store with 72-hour OVERDUE tracking.
+- Built-in providers: Z.ai, Anthropic, GitHub (classic + fine-grained), GitLab, Figma, PyPI, npm, Linear, Stripe, OpenAI, Slack.
+- Bash escape-hatch detection (the unique IP — `${VAR:+SET}${VAR:-UNSET}` bug class).
+- `TOKEN_HUNT_DISABLE=1` env var opt-out (skip all hooks).
+- `TOKEN_HUNT_ALLOW=1` env var bypass (one-shot override of BLOCK hooks).
+- Fail-closed behavior: scanner crashes BLOCK with bypass hint, never silently allow.

token_hunt-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing
+
+Thanks for considering a contribution.
+
+## Setup
+
+```bash
+git clone https://github.com/JordanNewell/token-hunt
+cd token-hunt
+pip install -e ".[dev]"
+pytest
+```
+
+## Development workflow
+
+1. Open an issue describing the change (skip for trivial fixes).
+2. Branch from `main`: `feat/<short-desc>` or `fix/<short-desc>`.
+3. Add tests for new behavior. TDD preferred.
+4. Run `pytest` and `ruff check .` before committing.
+5. Open a PR — describe the change + link the issue.
+
+## Adding a new provider pattern
+
+1. Add a rule to `src/token_hunt/patterns/builtin.toml` (gitleaks-compatible TOML format).
+2. Add provider metadata to `src/token_hunt/patterns/rotate-urls.toml`.
+3. Add a fake-format test constant to `tests/fixtures.py`.
+4. Add a detection test to `tests/test_regex_scanner.py`.
+
+## Code style
+
+- Python 3.10+ (use `from __future__ import annotations`).
+- Line length 100 (ruff default).
+- No AI-attribution trailers in commit messages.
+- Tests required for all behavior changes.
+
+## Commit message conventions
+
+Conventional commits: `feat:`, `fix:`, `docs:`, `test:`, `chore:`, `refactor:`.
+
+72-char subject line. Body wraps at 80. Explain the *why* when non-obvious.

token_hunt-0.1.0/LICENSE

@@ -0,0 +1,113 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Jordan Newell
+Licensed Work:        The token-hunt source code, documentation, and
+                      bundled assets, as made available at
+                      https://github.com/JordanNewell/token-hunt
+Additional Use Grant: You may use the Licensed Work, including in production,
+                      for any personal or noncommercial purpose. A
+                      noncommercial purpose is any purpose other than a
+                      commercial one, and specifically includes use by
+                      charitable organizations, educational institutions,
+                      public research organizations, and government agencies.
+                      Any commercial use of the Licensed Work requires a
+                      separate, written commercial license agreement with the
+                      Licensor.
+Change Date:          2030-10-12
+Change License:       MIT
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor
+as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+To specify as the Change License the GPL Version 2.0 or any later version, or
+a license that is compatible with GPL Version 2.0 or a later version, where
+"compatible" means that software provided under the Change License can be
+included in a program with software provided under GPL Version 2.0 or a later
+version. Licensor may specify additional Change Licenses without limitation.
+
+To either: (a) specify an additional grant of rights to use that does not
+impose any additional restriction on the right granted in this License, as
+the Additional Use Grant; or (b) insert the text "None".
+
+Not to modify this License in any other way.
+
+Change License Text
+
+MIT License
+
+Copyright (c) 2026 Jordan Newell
+
+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.

token_hunt-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: token-hunt
+Version: 0.1.0
+Summary: Catch secrets at chat time, not commit time. Hook-based scanner for Claude Code / Cursor / Aider.
+Project-URL: Homepage, https://github.com/JordanNewell/token-hunt
+Project-URL: Documentation, https://github.com/JordanNewell/token-hunt#readme
+Project-URL: Issues, https://github.com/JordanNewell/token-hunt/issues
+Author-email: Jordan Newell <jordan@jordannewell.com>
+License-Expression: BUSL-1.1
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Requires-Dist: watchdog>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# token-hunt
+
+> Catch secrets at chat time, not commit time.
+
+[![release](https://img.shields.io/badge/release-0.1.0-blue)](https://github.com/JordanNewell/token-hunt/releases)
+[![license](https://img.shields.io/badge/license-BUSL--1.1-green)](LICENSE)
+[![python](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/)
+
+Hook-based secret scanner for **Claude Code**. Catches leaks when you paste, when your agent reads, and when your agent's tools return — not at commit time when it's already too late.
+
+_Cursor and Aider supported via the CLI peer today (manual wiring); first-class plugin integrations ship in v0.2._
+
+## Why
+
+Existing scanners (gitleaks, trufflehog, ggshield) scan **git history**. By the time you run `git commit`, your secret has been in the AI chat transcript for 30+ minutes — indexed by Anthropic, sync'd to other machines, possibly read by the agent and re-emitted in subsequent tool calls.
+
+token-hunt catches at chat time. **Zero cloud, zero telemetry, fail-closed by default.**
+
+## Install
+
+**Pre-release (today):** not yet on PyPI or the Claude Code plugin marketplace. Install from source:
+
+```bash
+git clone https://github.com/JordanNewell/token-hunt
+cd token-hunt
+pip install -e .
+```
+
+**Post-v0.1.0 publication** (once tag is pushed and CI completes):
+
+```bash
+pip install token-hunt                              # standalone CLI
+claude plugin install token-hunt@JordanNewell       # Claude Code plugin
+```
+
+## 60-second demo
+
+```bash
+# In one terminal:
+pip install token-hunt
+
+# Scan a file:
+echo "ANTHROPIC_API_KEY=sk-ant-..." > /tmp/test.txt
+token-hunt scan /tmp/test.txt
+
+# Watch a directory (e.g. Claude Code transcript dir):
+token-hunt watch ~/.claude/projects/
+
+# List open leaks:
+token-hunt list
+
+# Close after rotating:
+token-hunt close 1 --note "rotated at console.anthropic.com"
+```
+
+## Detection points
+
+| Hook | What it sees | Action on leak |
+|---|---|---|
+| `UserPromptSubmit` | Your paste | WARN (banner) |
+| `PreToolUse:Bash` | Command about to run | BLOCK (won't run) |
+| `PostToolUse:Bash` | Command output | WARN + log (transcript already has it) |
+| `PostToolUse:Read` | File contents | WARN + log |
+| `PreToolUse:Edit/Write` | New file content | BLOCK |
+| `PostToolUse:Edit/Write` | Echo | WARN + log |
+
+## The unique feature: bash escape-hatch detection
+
+token-hunt catches patterns where bash evaluates a secret into emitted text, even when the literal secret isn't in your input:
+
+```bash
+# BLOCKED — both branches run, leaks the value:
+echo ${ANTHROPIC_API_KEY:+SET}${ANTHROPIC_API_KEY:-UNSET}
+
+# BLOCKED — direct echo of secret var:
+echo $GITHUB_TOKEN
+
+# ALLOWED — correct status-check pattern:
+[ -n "$ANTHROPIC_API_KEY" ] && echo SET
+```
+
+No other scanner detects this class.
+
+## Configuration
+
+Patterns layer (later extends earlier):
+
+1. `token_hunt/patterns/builtin.toml` (ships with package)
+2. `~/.token-hunt/patterns.local.toml` (machine-local, gitignored)
+3. `./.token-hunt/patterns.local.toml` (repo-local, gitignored)
+
+Allowlist (test fixtures, etc.):
+
+`~/.token-hunt/allowlist.toml`:
+```toml
+fingerprints = [
+  "abc123def456...",  # SHA-256 first 16 chars of allowlisted value
+]
+```
+
+Per-repo opt-out:
+```bash
+export TOKEN_HUNT_DISABLE=1
+```
+
+## Bypass
+
+Only the PreToolUse BLOCK hooks (Bash, Edit/Write) honor `TOKEN_HUNT_ALLOW`. The WARN hooks (UserPromptSubmit, PostToolUse:*) always fire — they don't block, so bypass is unnecessary.
+
+```bash
+TOKEN_HUNT_ALLOW=1 <command>  # one-shot bypass of BLOCK-level hooks (use sparingly)
+```
+
+## Built-in providers
+
+**Dev/infra:** Z.ai · Anthropic · GitHub (classic + fine-grained) · GitLab · Figma · PyPI · npm · Linear · Stripe · OpenAI · Slack
+
+**LLM inference (48 rules, 2026-10-15):** OpenRouter · Groq · Together · Fireworks · Mistral · xAI · Perplexity · Hugging Face · Cerebras · Replicate · Vercel AI Gateway · NVIDIA NIM · Chutes · Requesty · Novita · Upstage · Baseten · Baidu Qianfan · fal.ai · Alibaba DashScope · Moonshot Kimi · Cohere · Scaleway · SambaNova · Nebius · AI21 · OVHcloud · FriendliAI · GMI Cloud · Crusoe · Featherless · DeepInfra · Inference.net · BytePlus
+
+Providers whose keys are bare `sk-` (DeepSeek, StepFun, Moonshot, SiliconFlow, Poe, Qwen) are caught by the unattributed `sk-` rule; JWT-issued keys (MiniMax, DeepInfra scoped, Crusoe CLI) by the generic JWT rule. Providers with no publicly documented key format (SambaNova, Nebius, AI21, OVHcloud, FriendliAI, GMI Cloud, Crusoe, Featherless, DeepInfra, Inference.net, BytePlus) get **keyword-gated opaque rules**: the provider name must appear in the scanned text AND a 32+-char token must be present. Low-precision by design — the value is attribution and the rotation URL in the warn banner, not shape confidence.
+
+## token-hunt vs pat-scanner
+
+[pat-scanner](https://github.com/JordanNewell/pat-scanner) is the one-command Claude Code plugin: one hook, 13 credential classes, regex matching. Install it and you're covered.
+
+token-hunt is the engine underneath: the Python package, the CLI (`scan / list / close / watch`), six hooks with block-and-rotate behavior, the allowlist, and the bash escape-hatch runtime detector — the class regex can't see. Use pat-scanner when you just want the guard. Use token-hunt when you want the full scanner and the rotation workflow.
+
+## Comparison
+
+<sup>Verified 2026-07-27. Re-check competitor claims before citing in marketing.</sup>
+
+| Tool | Surface | Local-only | Fail-closed | Escape hatch | Fleet sync |
+|---|---|---|---|---|---|
+| **token-hunt** | Claude Code + CLI | yes | yes | **yes** | v0.2 |
+| sensitive-canary | Claude Code | yes | yes | no | no |
+| ggshield | Claude Code | no (cloud API) | no (fail-open) | no | no |
+| gitleaks | git + filesystem + stdin | yes | n/a | no | no |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest                 # full suite (85 tests)
+pytest --cov=token_hunt
+ruff check .           # lint (line-length 100, target py310)
+```
+
+Python ≥ 3.10. Runtime deps: `click` (CLI), `platformdirs` (config paths),
+`watchdog` (watch mode), `tomli` (< 3.11 only).
+
+### Layout
+
+```
+src/token_hunt/    engine, regex scanner, escape-hatch detector, entropy,
+                   patterns loader, allowlist, JSONL store, click CLI
+plugin/            Claude Code plugin manifest + 6 hook shell scripts
+tests/             unit + hook wiring + e2e tests
+```
+
+## License
+
+BUSL-1.1. Source-available; converts to MIT on 2030-10-12. See [LICENSE](LICENSE).
+
+## Security
+
+See [SECURITY.md](SECURITY.md). 72-hour acknowledgment SLA.