convez.ai
SkillAutomaçãoAvançado
chimera-defi

Token Reduce Skill

chimera-defi/token-reduce-skill

Orquestração inteligente de tokens com roteamento automático e guardrails

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill 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-skill

1 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

Estrelas
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
—
Issues abertas
3
Contribuidores
6

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

Claude Code Codex MCP MIT

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.txt for 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-skill for planner-first delegation to cheaper Kimi subagents (standalone repo integration)
  • token-savior for exact symbol / impact acceleration
  • context-mode for output-heavy payload sessions
  • headroom as an optional pilot proxy/MCP layer for large tool-result and long-session context pressure; token-reduce remains the master router
  • code-review-graph for large-repo structural review tasks
  • caveman for optional terse output and memory-file compression

Not in default routing

  • token-optimizer-mcp, token-optimizer, and infra-coupled claude-context are 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 to qmd collection add
  • TOKEN_REDUCE_QMD_EXTENSIONS: comma-separated extension list used to build the default mask
  • TOKEN_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 runtime qmd search latency before falling back to scoped rg (default: 8 in runtime, 0 in 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

ToolDescription
token_reduce_pathsReturn the smallest useful candidate path list for a repo query
token_reduce_snippetReturn a path-first result plus one ranked excerpt
token_reduce_benchmarkRun the local token-reduction benchmark and return the summary table
token_reduce_measureMeasure recent token-reduce adoption and write fresh repo-local artifacts
token_reduce_self_reviewGenerate a telemetry-driven self-review with prioritised next improvements
token_reduce_setupReturn plugin and MCP install instructions for this repo
token_reduce_full_setupRun one-command full setup (installs QMD + RTK, wires hook layers, indexes repo)
anthropic_cache_planAnnotate 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-snippet for clarification/repeat behavior
  • promote: token-reduce-structural for symbol/impact queries when available
  • recommendations: context-mode and code-review-graph only 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)

StrategyTokensvs broad inventory
broad_inventory980baseline
guidance_scoped_rg22177.4% saved
qmd_files24375.2% saved
token_reduce_paths_warm24575.0% saved
token_reduce_snippet_warm37361.9% saved

Composite benchmark (references/benchmarks/composite-benchmark.json)

StrategyTokensvs broad shellStatus
broad_shell1560baselineok
qmd_only67856.5% savedok
token_reduce_only38975.1% savedquality-fail
token_savior_only21386.3% savedquality-fail
rtk_only77350.4% savedok
composite_stack33878.3% savedquality-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_pct from quality-passing composite benchmark artifacts
  • realized_savings_estimate_pct discounted by observed helper usage + discovery compliance
  • reliability penalties (error/retry overhead + latency)
  • telemetry confidence (sample size + logging coverage quality)
  • telemetry windows (1d and 14d) 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-improve
  • token-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

Ver o original no GitHub

Bom para

Relacionados