Token Reduce Skill
chimera-defi/token-reduce-skill
Orquestração inteligente de tokens com roteamento automático e guardrails
Ver no GitHubSkill de orquestração para otimização de contexto em agentes Claude. Implementa descoberta de baixo custo com roteamento automático entre camadas (path/snippet/estrutural), integra suite de dependências (QMD, RTK) e bloqueia chamadas custosas antes da execução.
Instalação
npx convez-ai chimera-defi/token-reduce-skill1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Reduzir consumo de tokens em agentes multi-ferramenta
- Descoberta eficiente de código e documentação em repositórios grandes
- Implementar gates de enforcement para evitar chamadas custosas
- Integração automatizada de ferramentas com benchmarking operacional
Veredito

Ferramenta madura e bem arquitetada para agentes que precisam gastar tokens estrategicamente. Melhor para times que já usam Claude em escala e querem controle fino sobre custos de context; exige entendimento sólido de orchestração de agentes.
README
A tradução para o português deste README ainda está na fila.
token-reduce
token-reduce is an orchestration layer for agent context spending.
It provides built-in routing/enforcement, installs and wires downstream tools, and tells Claude/Codex when to use each tool path.
Agents: start with
llms.txtfor compact install/usage instructions.
What It Is
token-reduce is not just a prompt style or a single helper script.
It is a high-level token orchestration kit that:
- enforces low-cost discovery first
- auto-routes between path/snippet/structural tiers
- wires tool hooks so wasteful calls are blocked before execution
- integrates a dependency suite and operational benchmarking/review gates
Dependency Suite (Feature)
token-reduce treats dependency integration as a first-class feature.
Instead of manually managing tool-by-tool setup, it installs/wires defaults and exposes conditional tiers explicitly.
Core orchestrated stack
- QMD: BM25 path/snippet retrieval
- RTK: output compression for executed commands
- token-reduce helpers/hooks: path/snippet/adaptive routing + enforcement
Conditional companions
- AXI (
gh-axi,chrome-devtools-axi) for GitHub/browser-heavy execution kimi-delegate-skillfor planner-first delegation to cheaper Kimi subagents (standalone repo integration)token-saviorfor exact symbol / impact accelerationcontext-modefor output-heavy payload sessionsheadroomas an optional pilot proxy/MCP layer for large tool-result and long-session context pressure; token-reduce remains the master routercode-review-graphfor large-repo structural review taskscavemanfor optional terse output and memory-file compression
Not in default routing
token-optimizer-mcp,token-optimizer, and infra-coupledclaude-contextare intentionally excluded from default routing.- Legacy graphify-first orchestration is not part of active routing.
Install And Activation
Quick setup (core stack + hooks + wrappers):
git clone https://github.com/chimera-defi/token-reduce-skill tools/token-reduce-skill
./tools/token-reduce-skill/scripts/setup.sh
What setup.sh does automatically:
- installs/configures core tools (
qmd,rtk) when possible - runs initial QMD indexing for docs+code (
**/*.{md,txt,rst,py,sh,...}), which can take longer on first run - wires Claude hooks for prompt steering + pre-tool enforcement
- links global wrappers (
token-reduce-adaptive,token-reduce-paths,token-reduce-snippet,token-reduce-manage) - links the Codex skill and companion skills when present
Optional QMD scope overrides:
TOKEN_REDUCE_QMD_MASK: explicit glob mask passed toqmd collection addTOKEN_REDUCE_QMD_EXTENSIONS: comma-separated extension list used to build the default maskTOKEN_REDUCE_QMD_REFRESH_TTL_SECONDS: controls how often collection fingerprints are recomputed before refresh checks (default runtime:900)TOKEN_REDUCE_QMD_SEARCH_TIMEOUT_SECONDS: cap runtimeqmd searchlatency before falling back to scopedrg(default:8in runtime,0in benchmark/test contexts)
Standalone companion integration (kimi-delegate-skill):
git clone https://github.com/chimera-defi/kimi-delegate-skill /root/.openclaw/workspace/dev/kimi-delegate-skill
./tools/token-reduce-skill/scripts/integrate-kimi-delegate.sh
One-command measured activation (core-only default + validate):
git clone https://github.com/chimera-defi/token-reduce-skill tools/token-reduce-skill
./tools/token-reduce-skill/scripts/token-reduce-manage.sh activate-stack
Enable conditional companion install during activation:
TOKEN_REDUCE_ACTIVATE_EXTENDED_STACK=1 ./tools/token-reduce-skill/scripts/token-reduce-manage.sh activate-stack
Direct optional companion install surface:
TOKEN_REDUCE_INSTALL_EXTENDED_STACK=1 ./tools/token-reduce-skill/scripts/setup.sh
Host Support
Claude Code
git clone https://github.com/chimera-defi/token-reduce-skill tools/token-reduce-skill
./tools/token-reduce-skill/scripts/setup.sh
The skill is then available as /token-reduce in any Claude Code session rooted in the repo.
Codex
git clone https://github.com/chimera-defi/token-reduce-skill "$CODEX_HOME/skills/token-reduce"
Codex fresh-context handoff generator:
./tools/token-reduce-skill/scripts/token-reduce-manage.sh handoff-codex
MCP
{
"mcpServers": {
"token-reduce-mcp": {
"command": "node",
"args": ["/absolute/path/to/token-reduce-skill/mcp/server.mjs"]
}
}
}
Available MCP Tools
| Tool | Description |
|---|---|
token_reduce_paths | Return the smallest useful candidate path list for a repo query |
token_reduce_snippet | Return a path-first result plus one ranked excerpt |
token_reduce_benchmark | Run the local token-reduction benchmark and return the summary table |
token_reduce_measure | Measure recent token-reduce adoption and write fresh repo-local artifacts |
token_reduce_self_review | Generate a telemetry-driven self-review with prioritised next improvements |
token_reduce_setup | Return plugin and MCP install instructions for this repo |
token_reduce_full_setup | Run one-command full setup (installs QMD + RTK, wires hook layers, indexes repo) |
anthropic_cache_plan | Annotate Anthropic API payloads with cache_control and estimate repeated-call savings |
Routing Model
Default first move:
token-reduce-adaptive <topic words>
Tier behavior:
- base:
token-reduce-paths - promote:
token-reduce-snippetfor clarification/repeat behavior - promote:
token-reduce-structuralfor symbol/impact queries when available - recommendations:
context-modeandcode-review-graphonly for matching task classes
Disable adaptive hinting if needed:
TOKEN_REDUCE_ADAPTIVE_HINT=0
Benchmarks And Regression Guard
Local benchmark (references/benchmarks/local-benchmark.json)
| Strategy | Tokens | vs broad inventory |
|---|---|---|
broad_inventory | 980 | baseline |
guidance_scoped_rg | 221 | 77.4% saved |
qmd_files | 243 | 75.2% saved |
token_reduce_paths_warm | 245 | 75.0% saved |
token_reduce_snippet_warm | 373 | 61.9% saved |
Composite benchmark (references/benchmarks/composite-benchmark.json)
| Strategy | Tokens | vs broad shell | Status |
|---|---|---|---|
broad_shell | 1560 | baseline | ok |
qmd_only | 678 | 56.5% saved | ok |
token_reduce_only | 389 | 75.1% saved | quality-fail |
token_savior_only | 213 | 86.3% saved | quality-fail |
rtk_only | 773 | 50.4% saved | ok |
composite_stack | 338 | 78.3% saved | quality-fail |
This reports the current potential token-savings ceiling and flags quality failures honestly; do not treat quality-failing strategies as release-ready wins.
Honest outcome reporting (anti-gaming)
Benchmark savings above are potential ceiling metrics only. For realistic outcomes, run composite telemetry:
./scripts/token-reduce-manage.sh composite
The report now separates:
potential_savings_pctfrom quality-passing composite benchmark artifactsrealized_savings_estimate_pctdiscounted by observed helper usage + discovery compliance- reliability penalties (error/retry overhead + latency)
- telemetry confidence (sample size + logging coverage quality)
- telemetry windows (
1dand14d) so current behavior is not hidden by stale history
This prevents claiming benchmark-only wins when adoption/compliance or runtime stability are weak.
Release gate (anti-regression)
Use this for major change sets:
./scripts/token-reduce-manage.sh release-gate
It gates on:
- composite savings + quality
- adaptive savings + quality (with a small default overhead tolerance of
-2.0%for benchmark noise) - profile viability
- runtime reliability (
helper_error_rate, failure overhead, retry overhead)
Operational Commands
./scripts/token-reduce-manage.sh checkpoint
./scripts/token-reduce-manage.sh benchmark
./scripts/token-reduce-manage.sh benchmark-adaptive
./scripts/token-reduce-manage.sh benchmark-composite
./scripts/token-reduce-manage.sh benchmark-profiles
./scripts/token-reduce-manage.sh release-gate
./scripts/token-reduce-manage.sh sync-benchmarks
./scripts/token-reduce-manage.sh test-adaptive
./scripts/token-reduce-manage.sh validate
./scripts/token-reduce-manage.sh measure
./scripts/token-reduce-manage.sh review
./scripts/token-reduce-manage.sh composite
./scripts/token-reduce-manage.sh doctor
checkpoint is the consistent maintenance harness: it runs release gate/validate/tests + local/global measure/review + workspace audit + dry-run telemetry sync and writes checkpoint artifacts under artifacts/token-reduction/.
release-gate automatically refreshes README benchmark token rows from the generated artifacts; sync-benchmarks can be run manually when needed.
Weekly automation (telemetry pull + skill improvement pass):
./scripts/install-token-reduction-cron.sh
This installs Monday cron entries for:
token-reduce-manage.sh self-improvetoken-reduce-manage.sh telemetry-sync
Dependency checks:
- core only:
deps-check,deps-update - conditional companions:
deps-check-conditional,deps-update-conditional
Caveman Status
caveman is integrated as an optional companion, not forced globally.
- enable terse output when requested:
/caveman lite - compress memory file when requested:
/caveman:compress CLAUDE.md
Default token-reduce routing/enforcement works with or without caveman.
Learn More
- references/INDEX.md
- references/companion-tools.md
- references/kimi-delegate-integration.md
- references/feature-matrix.md
- references/tier-value-profile.md
- references/headroom-evaluation-2026-06-10.md
- references/token-reduction-guide.md
- references/composite-benchmark.md
- references/profile-presets.md
- references/prompt-stack-intake-2026-04-18.md
- references/meta-learnings-2026-04-18.md
- references/meta-learnings-2026-04-19.md
- references/meta-learnings-2026-04-25.md
- references/meta-learnings-2026-05-06.md
- references/meta-learnings-2026-05-20.md
- references/agent-setup.md
- references/workspace-integration.md
- references/codex-handoff.md
- references/caveman-evaluation.md
- references/axi-evaluation.md
- references/token-savior-evaluation.md