[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81991":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":14,"stars7d":15,"stars30d":16,"stars90d":13,"forks30d":13,"starsTrendScore":17,"compositeScore":18,"rankGlobal":8,"rankLanguage":8,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":8,"pushedAt":8,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":13,"starSnapshotCount":13,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},81991,"guardians_of_the_token","tonylee2016\u002Fguardians_of_the_token","tonylee2016",null,"Python",74,6,3,0,16,33,42,48,2.54,"MIT License",false,"main",[],"2026-06-12 02:04:22","# GOT\n\n[![PyPI package](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fguardians-of-the-token?label=pypi%20package)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fguardians-of-the-token\u002F)\n[![PyPI downloads](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fdm\u002Fguardians-of-the-token?label=pypi%20downloads)](https:\u002F\u002Fpypistats.org\u002Fpackages\u002Fguardians-of-the-token)\n[![Supported Python version](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fpython-%3E%3D3.9-blue?label=supported%20python%20version)](https:\u002F\u002Fpypi.org\u002Fproject\u002Fguardians-of-the-token\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fl\u002Fguardians-of-the-token?label=license)](LICENSE)\n[![GitHub stars](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Ftonylee2016\u002Fguardians_of_the_token?style=social)](https:\u002F\u002Fgithub.com\u002Ftonylee2016\u002Fguardians_of_the_token\u002Fstargazers)\n[![CI](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Ftonylee2016\u002Fguardians_of_the_token\u002Fci.yml?branch=main&label=ci)](https:\u002F\u002Fgithub.com\u002Ftonylee2016\u002Fguardians_of_the_token\u002Factions\u002Fworkflows\u002Fci.yml)\n\n![GOT hero image](assets\u002Fgot-hero-cartoon.png)\n\n**Guardians of the Token** is a safety layer for agentic coding sessions. It helps Claude Code, Codex, and other LLM clients avoid accidental context explosions from huge files, oversized web fetches, and noisy tool output.\n\nLLM agents are powerful because they can read, run, fetch, and reason. GOT keeps that power controlled.\n\n![Prompt guard demo](assets\u002Fprompt-guard-demo.gif)\n\n## Why GOT\n\nAgentic coding tools can burn through context in one bad move:\n\n- reading a giant log or transcript into chat\n- dumping command output that should have gone to a file\n- fetching a large page directly into model context\n- carrying stale session history until compaction degrades continuity\n\nGOT watches the risky paths and turns them into a clear pause:\n\n```text\n🛡️ Guardians of the Token blocked this command.\nTarget: \u002Ftmp\u002Fguardians_test_compact\nEstimate: ~200,000 tokens (50% of the 400,000-token window)\nCurrent context: ~0 tokens (0%)\nNext options:\n- Inspect the beginning\n- Inspect the end\n- Search for a term\n- Summarize a bounded section\n- Bypass once for the full file\n```\n\nThe goal is simple: prevent accidental context damage while keeping the agent moving.\n\n## What It Guards\n\n| Client | Guarded paths |\n| --- | --- |\n| Claude Code | `Read`, `Bash`, `WebFetch`, oversized tool output, **off-topic prompts in large sessions** |\n| Codex | risky `Bash` file dumps, URL fetches, oversized Bash output |\n| MCP clients | guarded source indexing and bounded file tools through `guardians-mcp` |\n| API workflows | experimental request-size proxy through `guardians-proxy` |\n\n## Product Principles\n\n- **Warn before context is wasted.** Large reads and fetches are blocked before they enter the conversation.\n- **Suggest intent, not shell incantations.** GOT offers high-level next steps; the agent handles the mechanics.\n- **Prefer bounded work.** Inspect, search, summarize, and only bypass when the user explicitly wants the full payload.\n- **Use one language across clients.** Claude and Codex have different hook surfaces, but users see the same warning style.\n- **Stay local-first.** Hooks run locally and use lightweight token estimates.\n\n## Install\n\nInstall the PyPI package:\n\n```bash\npython3 -m pip install guardians-of-the-token\n```\n\nThen run the installer:\n\n```bash\nguardians-install\n```\n\nThe package name is `guardians-of-the-token`. The Python import package is\n`guardians_of_the_token`.\n\n`guardians-install` shows a terminal banner, detects supported local clients,\nand presents a checkbox selector for individual integrations:\n\n- Codex CLI hooks\n- Codex app MCP\n- Claude Code hooks\n- Claude Desktop MCP\n- automatic updates\n\nUse Up\u002FDown to move, Space to toggle, and Enter to install the selected\nintegrations. Use `guardians-install --yes` to install into all detected\nintegrations without prompting.\n\nAutomatic updates are selected by default. They run only from safe session-start\nand update paths, never from hot tool hooks.\n\nIf your Python environment blocks global installs, use a virtual environment or\n`pipx`:\n\n```bash\npipx install guardians-of-the-token\nguardians-install\n```\n\nFrom a checkout during development:\n\n```bash\npython3 -m pip install -e .\nguardians-install\n```\n\nManual install commands:\n\n- Codex workspace hooks:\n\n```bash\nguardians-codex-install \u002Fpath\u002Fto\u002Fworkspace\n```\n\n- Claude Code workspace hooks:\n\n```bash\nguardians-claude-install \u002Fpath\u002Fto\u002Fworkspace\n```\n\n- Codex global hooks + MCP registration:\n\n```bash\nguardians-codex-install --global\n```\n\n- Claude Code global hooks:\n\n```bash\nguardians-claude-install --global\n```\n\nRun the experimental MCP demo server:\n\n```bash\nguardians-mcp\n```\n\nRun the experimental HTTP proxy:\n\n```bash\nguardians-proxy\n```\n\n## How It Works\n\nGOT estimates token impact with a conservative heuristic:\n\n```text\nstage 1: size + type hint\nstage 2: small text sample near threshold (files only)\n```\n\nBefore a risky operation runs, the relevant hook checks file size, URL `HEAD`\nmetadata, or command shape. File preflight stays cheap by sampling only when an\nestimate lands near the warning threshold. After a tool runs, post-hooks\nsuppress output above the soft cap before it enters model context.\n\nWhen a request is too large, GOT blocks it and returns a shared warning template with:\n\n- the target\n- estimated token impact\n- current context estimate when available\n- compaction risk when relevant\n- high-level next options\n\n## Prompt Guard (Claude Code only)\n\nOnce a session crosses ~30% of the model's context window, GOT also checks\neach new prompt for topical drift. If the prompt looks unrelated to the\nongoing conversation it blocks the submission before Claude processes it,\nsaving you a round-trip's worth of input tokens.\n\nYou'll see a block message like:\n\n```text\n🛡️ Guardians blocked this prompt before Claude processed it.\n\nReason: this looks unrelated to the current large Claude session and would\nsend a lot of unrelated context.\nSimilarity: 0.07 (block threshold 0.10)\nContext: 168.9k \u002F 200.0k tokens (84%)\nEstimated cost if sent: $0.5068\n\nTo continue anyway, resend the same prompt prefixed with GOT_UNBLOCK.\n```\n\nTo override a block, resend the prompt with the configured prefix:\n\n```text\nGOT_UNBLOCK \u003Cyour prompt>\n```\n\nA small ONNX embedding model (~22 MB, `all-MiniLM-L6-v2`) is downloaded\nautomatically the first time you run `guardians-install`. You can also fetch\nit manually:\n\n```bash\nguardians-download-models\n```\n\nConfigure the guard in `~\u002F.guardians.json`:\n\n```json\n{\n  \"prompt_guard\": {\n    \"enabled\": true,\n    \"block_context_pct\": 0.30,\n    \"very_low_similarity\": 0.10,\n    \"unblock_prefix\": \"GOT_UNBLOCK\"\n  }\n}\n```\n\nSet `\"enabled\": false` to disable it entirely. All decisions (allow and\nblock) are logged to `.got\u002Fevents.jsonl` with the gate that fired.\n\n## Experimental Surfaces\n\nThe production-quality integrations today are the Claude Code and Codex hooks.\n\n`guardians-mcp` exposes lightweight preflight and bounded file-access tools\nfor Claude Desktop Projects and other MCP clients. It cannot intercept native\nfile uploads, but it can make projects guard-aware by checking file size before\nClaude reads a source and by giving Claude safe head, tail, search, and chunk\ntools.\n\nRecommended Claude Project workflow:\n\n1. Run `guardians-project-init \u002Fpath\u002Fto\u002Fproject`.\n2. Review the GOT policy block appended to that project's `CLAUDE.md`.\n3. Use `got_file_size` before analyzing a new or potentially large local file.\n4. Use bounded tools instead of raw full-file ingestion when risk is warning or\n   critical.\n\nGOT MCP is intended as a preflight for unknown, new, or potentially large\nsources. If a source is classified as `safe`, Claude should proceed normally\nwith native tools instead of routing ordinary small-file work through GOT.\n\nMCP project state is stored under `.\u002F.got\u002F` by default:\n\n```text\n.got\u002F\n  GUARDIANS_PROJECT_POLICY.md\n  index\u002F\n```\n\nSet `GUARDIANS_INBOX=\u002Fpath\u002Fto\u002Fdir` before starting `guardians-mcp` to use a\ndifferent storage directory.\n\nKey MCP tools:\n\n- `got_project_init`\n- `got_project_policy`\n- `got_file_size`\n- `got_url_size`\n- `got_file_head`\n- `got_file_tail`\n- `got_file_search`\n- `got_file_chunk_summary`\n\n`guardians-proxy` is currently a minimal FastAPI proxy for Anthropic\u002FOpenAI-style message payloads. It estimates request size before forwarding, but it is not yet a full production gateway.\n\n## Configuration\n\nOptional user config lives at `~\u002F.guardians.json`:\n\n```json\n{\n  \"warn_threshold_pct\": 20,\n  \"default_input_price_per_million\": 3.0,\n  \"max_output_tokens\": 8000,\n  \"telemetry_enabled\": false,\n  \"telemetry_host\": \"https:\u002F\u002Fus.i.posthog.com\",\n  \"telemetry_api_key\": \"phc_...\",\n  \"update_check_enabled\": true,\n  \"auto_update_enabled\": true,\n  \"auto_update_interval_hours\": 24,\n  \"auto_update_include_major\": false\n}\n```\n\nProject config can live in `.guardians.toml`:\n\n```toml\nwarn_threshold_pct = 10\nmax_output_tokens = 8000\ndefault_input_price_per_million = 3.0\ntelemetry_enabled = false\n\nwhitelist = [\"README.md\", \"docs\u002F**\"]\nignore = [\"node_modules\u002F**\", \".git\u002F**\", \"dist\u002F**\", \"build\u002F**\"]\n```\n\nWhitelisted and ignored files are allowed through without blocking. Use this\nfor known-safe paths that agents often inspect.\n\nBypass is single-use:\n\n```bash\ntouch \u002Ftmp\u002Fguardians_bypass\n```\n\n## Local Reports\n\nGOT records blocked and suppressed operations locally under `.got\u002Fevents.jsonl`.\nTelemetry is off by default. If you opt in, GOT sends one anonymous install\nevent to a PostHog-compatible capture endpoint. It only sends anonymous\ninstallation ID, GOT version, Python version, and OS. GOT does not send IP as\nevent data and disables PostHog GeoIP enrichment. It never sends paths, URLs,\nprompts, file contents, command text, tool usage, risk levels, actions,\ngeolocation, or token counts. The installer shows telemetry as a default-on\nselectable option and writes your choice to `~\u002F.guardians.json`. You can\noverride it with `GUARDIANS_TELEMETRY=0` or `GUARDIANS_TELEMETRY=1`.\n\nManual update commands:\n\n```bash\nguardians update\nguardians update --check\n```\n\nPrint a local savings report:\n\n```bash\nguardians-report\n```\n\nRun the local dashboard:\n\n```bash\nguardians-dashboard\n```\n\nThe dashboard binds to `127.0.0.1:8766` by default and shows estimated tokens\nand dollars saved, top risky files\u002FURLs, and activity by client.\n\n## Test Fixtures\n\nGOT includes deterministic test stubs for hook development:\n\n| Fixture | Meaning |\n| --- | --- |\n| `\u002Ftmp\u002Fguardians_test_small` | small file estimate |\n| `\u002Ftmp\u002Fguardians_test_large` | large file estimate |\n| `\u002Ftmp\u002Fguardians_test_compact` | compaction-scale file estimate |\n| `https:\u002F\u002Fguardians-test\u002Flarge` | large URL estimate |\n| `https:\u002F\u002Fguardians-test\u002Fcompact` | compaction-scale URL estimate |\n\nThe install commands refresh the `\u002Ftmp\u002Fguardians_test_*` files with short,\nreadable fixture text. The hooks still use deterministic fake sizes for these\nexact paths, so the files do not need to be physically large. To test blocking,\nuse a full-read command such as:\n\n```bash\ncat \u002Ftmp\u002Fguardians_test_compact\n```\n\nFor a more realistic URL test, run the local fixture server:\n\n```bash\nguardians-test-server\n```\n\nIf the client cannot reach your host `127.0.0.1`, bind all interfaces instead:\n\n```bash\nguardians-test-server --host 0.0.0.0\n```\n\nThe server will print candidate LAN URLs you can use from a sandboxed app.\n\nThen fetch one of these URLs from Claude Code or Codex:\n\n```text\nhttp:\u002F\u002F127.0.0.1:8765\u002Flarge\nhttp:\u002F\u002F127.0.0.1:8765\u002Fcompact\n```\n\nThe server returns large `Content-Length` values to `HEAD` requests but only\nsmall readable bodies for `GET`, so hooks can test real pre-fetch size checks\nwithout downloading a large payload.\n\n## Project Layout\n\n```text\nguardians_of_the_token\u002F\n  claude\u002F      Claude Code hooks\n  codex\u002F       Codex hooks\n  messages.py  shared warning templates\n  guard.py     core token guard logic\n  mcp_server.py\n  proxy.py\n```\n\n## Status\n\nGOT is early, practical infrastructure for local LLM workflows. The current focus is preventing accidental context loss in Claude Code and Codex, then expanding toward richer byte-size tracking, model-aware thresholds, saved-output workflows, and session-health warnings.\n","Guardians of the Token 是一个为代理编码会话设计的安全层，旨在防止 Claude Code、Codex 等大型语言模型客户端因处理大文件、超大网页抓取或工具输出噪声而导致的上下文爆炸。其核心功能包括监控潜在风险路径并提供清晰的操作选项，如检查文件开头或结尾、搜索特定术语、摘要部分内容或一次性绕过整个文件。该项目适用于需要控制 LLM 代理行为以避免意外消耗大量上下文资源的场景。通过在执行前警告用户并建议替代操作，GOT 能够有效保持对话连续性和效率。",2,"2026-06-11 04:07:23","CREATED_QUERY"]