token-optimizer
/token-optimizer
Przeszukuje kod i nawiguje architekturą przez analizę AST zamiast grep i find, co zmniejsza zużycie tokenów.
- Autor
- tokensafe-dev ↗
- Repozytorium
- tokensafe ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 13.11.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 4
- Skrypty
- 0
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 0
Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
Co robi i kiedy
Przeszukuje kod i nawiguje architekturą przez analizę AST zamiast grep i find, co zmniejsza zużycie tokenów.
Oryginalny opis (EN)
MANDATORY code inspection and architecture navigation skill. Activate whenever inspecting files, searching code, locating components/functions/classes, reading implementations, analyzing dependencies, or navigating codebase architecture. Replaces wasteful terminal grep/find with zero-loss AST smart slicing (-90% tokens), extracts definitions with 1-hop dependencies, enforces security guards, and tracks token efficiency metrics.
Jak działa
- MANDATORY AGENT DIRECTIVES
- Core MCP Tools (tokensafe)
- Context Governor & History Compactor
- LLM Prompt Cache Optimization
- Proof-of-Savings Turn Footer (always in English)
Podgląd SKILL.md
---
name: token-optimizer
description: >-
MANDATORY code inspection and architecture navigation skill.
Activate whenever inspecting files, searching code, locating components/functions/classes,
reading implementations, analyzing dependencies, or navigating codebase architecture.
Replaces wasteful terminal grep/find with zero-loss AST smart slicing (-90% tokens),
extracts definitions with 1-hop dependencies, enforces security guards, and tracks token efficiency metrics.
---
# TokenSafe Optimization & Architecture Intelligence Skill
TokenSafe is the zero-loss token economy, context governor, and security engine for autonomous AI coding agents.
It replaces brute-force terminal crawls (`grep`, `find`, `cat`) with deterministic AST symbol extraction,
folds multi-turn conversation history, slices verbose tool outputs, and guards against secret leaks and destructive actions.
---
## MANDATORY AGENT DIRECTIVES
1. **ZERO RAW TERMINAL GREP / FIND (HARD-BLOCKED & REPLACED BY `scoped_search`)**:
- Strictly NEVER run `grep`, `egrep`, `ripgrep`, or `find` in `run_command` on source code files (`.ts`, `.tsx`, `.py`, `.js`, `src/`, `views/`, `components/`).
- Raw code searches via bash burn thousands of context tokens and are blocked by **TokenSafe Guard** (`decision: deny`).
- **Mandatory Search Tool (`scoped_search`)**: ALWAYS call `tokensafe:scoped_search(query, path=".", scope="code")` to search for text, identifiers, or symbol definitions across unknown files (-90% tokens). The `path` parameter specifies the search directory or project root (e.g. `"."`, `"./src"`). The `scope` parameter filters files (`"code"`, `"config"`, `"all"`), a file extension (`"go"`, `"ts"`), or a subfolder path (`"internal/promo"`).
2. **SYMBOL & COMPONENT EXTRACTION (`smart_read_file`)**:
- When locating or reading any function, component, class, or handler (e.g. `<LuckyWheelTab>`, `areSectorEqual`, `useWallet`), ALWAYS call `tokensafe:smart_read_file` with `path` (supports relative paths, e.g. `"src/service.ts"`) and `symbol`.
- **1-Hop Dependency Modes (`dep_mode` & `include_deps`)**: By default (`dep_mode="signature"`), `smart_read_file` returns the full target implementation plus compact 1-line 1-hop dependency signatures and collapsed imports (-95%+ tokens). Pass `"dep_mode": "full"` when full 1-hop dependency bodies are required, or `"include_deps": false` for 0-hop surgical isolation.
- **Cache Pointer Recovery (`force_full`)**: When repeating an unchanged read in the same MCP session, `smart_read_file` may return a compact pointer referencing the prior output. Reuse that earlier output; only pass `"force_full": true` if your context was compacted or you are a fresh subagent lacking prior turns.
- **Multi-Symbol Bundles (`smart_bundle`)**: When you need 3+ related symbols across several files, call `tokensafe:smart_bundle(targets=[{path, symbol}])` ONCE instead of chained `smart_read_file` calls (max 8 targets). It merges per-file skeletons, deduplicates shared import/type lines into one block, and unifies 1-hop dependency signatures — one roundtrip instead of many.
- **Schema Auto-Slicing**: OpenAPI/Swagger, Prisma, GraphQL and SQL files bypass AST skeletonization. Pass the spec path (`/users/{id}`), Prisma model, GraphQL type, or SQL table as `symbol` for a targeted slice with 1-hop references; an empty `symbol` returns a compact overview (paths/models/types/tables index) instead of a 20k-50k token dump.
- **Result**: Preserves the exact target definition while folding surrounding inert code into clean 1-line signatures without docstrings (-85% to -98% tokens).
3. **ARCHITECTURE SURVEY BEFORE BROWSING (`get_architecture_graph`)**:
- Before multi-file exploration or asking where things are located, ALWAYS call `tokensafe:get_architecture_graph(project_path=".")` (`project_path` defaults to active workspace).
- **Result**: Returns top architectural God Nodes, dependency hubs, and centrality rankings in < 250 tokens without file crawling.
4. **API SURFACE INSPECTION (`get_api_surface`)**:
- Call `tokensafe:get_api_surface(project_path=".")` (`project_path` defaults to active workspace) to get all exported classes, types, interfaces, and function signatures in a single compact markdown map.
5. **DIRECTORY NAVIGATION (`list_dir`)**:
- NEVER run `ls -la` or `ls -l` in terminal.
- Call `tokensafe:list_dir(path=".", depth=2)` for clean directory trees without permissions, timestamps, or lockfiles (-90% tokens). Supports relative subfolders (`path="src"`).
6. **SURGICAL FILE EDITS (`edit_file`)**:
- On existing files with >= 40 lines, wholesale rewrites via `write_file` are blocked by **Output Guard**. Always use `edit_file` with precise `Target` and `Replacement` blocks.
7. **SECRET LEAK PREVENTION (ZERO HARDCODED FALLBACKS)**:
- Never provide real private keys, API secrets, or credentials as fallback values in `os.environ.get()` or `process.env`. Real credentials must exist strictly in environment variables.
8. **CONTEXT BUDGET BEFORE HEAVY WORK (`context_budget` → `compact_conversation`)**:
- Before large multi-step tasks, call `tokensafe:context_budget(model=...)` to check the window budget (tools/history/prompts breakdown, 50/80/95% thresholds).
- When it reports `warning` or `critical`, call `tokensafe:compact_conversation(transcript_path=...)` to fold past turns into a State Ledger before continuing — do not let context exhaustion degrade code quality mid-task.
9. **REPEAT READ DEDUPLICATION & CACHE POINTERS**:
- Never repeatedly re-read the same file or symbol within an active session.
- When `smart_read_file` returns a pointer hit (`// [TokenSafe: Pointer Hit for ...]`), reuse earlier context; pass `"force_full": true` only if your context was compacted or you are a fresh subagent lacking prior turns.
10. **ZERO-FLUFF EGRESS & SURGICAL DIFFS**:
- Eliminate conversational preambles, courtesy fillers, and trailing sign-offs.
- Never reprint full unmodified files or lengthy boilerplate; cite line ranges and provide targeted diffs.
11. **COMPACT TEST EXECUTION**:
- Run unit tests with concise flags or via `tokensafe tests [cmd]` so passing test suites emit a single-line summary (`PASS: ...`) rather than flooding `Messages` history with hundreds of verbose log lines. Full traceback is strictly preserved on failure.
---
## Core MCP Tools (`tokensafe`)
The full tool table with efficiency impact, JSON workflow examples, the Guard check matrix, and the CLI reference live in `references/` — read only the file you need:
- [`references/mcp-tools.md`](references/mcp-tools.md) — Core MCP Tools table + Agent Workflow JSON examples
- [`references/guard-checks.md`](references/guard-checks.md) — Security & Hygiene Guard check matrix (deny/ask per operation)
- [`references/cli-reference.md`](references/cli-reference.md) — `tokensafe` CLI command reference
Quick pointers:
- Search: `tokensafe:scoped_search(query, path=".", scope="code")` — safe keyword & symbol search, never raw grep.
- Inspect: `tokensafe:smart_read_file(path, symbol)` — definition + 1-hop deps.
- Bundle: `tokensafe:smart_bundle(targets=[{path, symbol}])` — 3-8 related symbols across files in one call, shared imports deduplicated.
- Navigate: `tokensafe:get_architecture_graph(project_path)` / `tokensafe:get_api_surface(project_path)`.
- Directory: `tokensafe:list_dir(path, depth=2)` — clean tree, never verbose `ls -la`.
- Terminal: `tokensafe:sanitize_command(command, cwd)` — bounded logs/diffs, test runner guards.
- Context: `tokensafe:compact_conversation(transcript_path)` / `tokensafe:context_budget`.
---
## Context Governor & History Compactor
For long-running autonomous sessions, TokenSafe actively manages context bloat:
1. **Multi-Turn History Compaction**:
- At conversation turn >= 3, automatically compiles past turns into a lean **Consolidated State Ledger**.
- Preserves active file paths, modified symbols, and pending tasks while discarding transient tool output noise.
- **Manual trigger**: call `tokensafe:compact_conversation` with the session's `transcript_path` any time you need to shed context between subtasks — it returns the ledger JSON plus exact original/folded token counts.
2. **Subagent Deduplication Firewall**:
- Caches file reads across subagents and sessions using SHA-256 content hashes. Interactive MCP clients receive self-healing pointer hits on unchanged repeat reads inside the same session; fresh subagents or post-compaction callers recover automatically with `force_full=true`.
3. **Loop Guard**:
- Detects repeated identical tool calls and triggers `force_ask` to prevent runaway infinite agent loops.
4. **Output Token Guard**:
- Intercepts wholesale `write_file` calls on existing files with >= 40 lines to prevent expensive output token burn.
---
## LLM Prompt Cache Optimization
TokenSafe actively maximizes provider KV-cache hit rates alongside token compression:
1. **Append-Only Epoch Architecture**: In proxy mode, past messages (`messages[0..N-2]`) are never retroactively mutated within an epoch, preserving prefix cache hits. When cumulative context reaches **80% of the model's window**, an atomic Epoch Rollover consolidates deep history into a State Ledger.
2. **Multi-Breakpoint Cache Control**: `PromptCacheNormalizer` sorts `tools` deterministically and places Anthropic `cache_control: {"type": "ephemeral"}` across tools, static system instructions, and the penultimate completed turn; OpenAI requests receive deterministic `prompt_cache_key`.
3. **Deterministic Prefix Normalization**: Ephemeral timestamps, hit counters, and session IDs are stripped from static prefixes, and `AgentFirewall` headers remain byte-deterministic across hits.
4. **Parametric Prompt Template Caching**: `DistillationCache` extracts file paths and symbols into positional slots (`<FILE_0>`, `<SYM_0>`) so structurally identical prompts hit L1/L2/L3 caches with 0 LLM roundtrips.
---
## Proof-of-Savings Turn Footer (always in English)
At the end of any response where tools were executed, files were inspected, commands were sanitized, or prompts were compacted, append a compact 1-line footer in English:
`⚡ **TokenSafe Turn Savings**: +<tokens> tokens saved on this turn (<breakdown>) | Cumulative Total: <total> tokens (≈$<usd> approx)`
The USD figure is **derived** (tokens × $1.5/M blended rate) — an approximation for planning, never a bill. Cumulative analytics distinguish `measured` (metered I/O delta) from `estimated` (counterfactual baseline) savings — see METRICS.md.
Pliki w paczce (4)
- SKILL.md 10 KB
- references/cli-reference.md 2 KB
- references/guard-checks.md 2 KB
- references/mcp-tools.md 6 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · tokensafe-dev/tokensafe | 100 | MIT |
| georgekhananaev/claude-skills-vault | 100 | MIT |
| nitinjain999/platform-skills | 95 | Apache-2.0 |
| samibajwaisking/Token-Optimizer-Skill | 95 | MIT |
| LeoYeAI/openclaw-master-skills | 90 | MIT |
| LeoYeAI/openclaw-master-skills | 90 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki bf3cf6becd18 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100ast-grep
Wyszukuje, analizuje i refaktoryzuje kod za pomocą ast-grep (sg): modyfikacje oparte na AST, wyszukiwanie strukturalne i linting. - 100ast-grep
Szuka i przepisuje kod przez drzewo składni za pomocą CLI ast-grep, gdy dopasowanie zależy od struktury. - 95ast-grep-search
Wyszukuje i zamienia wzorce kodu strukturalnie przez ast-grep, dopasowując kod według drzewa AST, na przykład funkcje o konkretnych sygnaturach lub antywzorce, których nie złapie regex. - 95codebase-search
Przeszukuje duże bazy kodu i pomaga w nawigacji: wzorce kodu, śledzenie wywołań funkcji, struktura kodu i lokalizowanie błędów przez wyszukiwanie semantyczne, grep i analizę AST. - 100structural-search
Wyszukuje kod po strukturze AST przy użyciu ast-grep, na przykład wywołania funkcji, importy lub definicje klas. - 100search-code
Wyszukuje wzorce w kodzie Syncpack, używając ast-grep dla Rust oraz grep i rg w pozostałych przypadkach.