token-efficacy

harness-config token posture

Maintainer hub for context-window efficiency across harnesses. Repo policy is in AGENTS.md §5 (Token Budget + Token efficacy) and openspec/changes/token-efficacy-program/. Do not add @RTK.md to shared instruction sources.

Overview

Agent sessions accumulate tokens from standing instructions, skill descriptions, tool schemas, shell output, and conversation history. This repo manages token efficacy through eight layers, each with a single primary owner. Stacking tools on the same layer (e.g. two session pruners) requires compare research, measurement, and an explicit decision gate.

Install policy

New OSS token tools (Sleev, Headroom, Cozempic, mcp-compressor, jCodeMunch, etc.) stay research-only until /research compare picks a category winner and the gates below approve installation.

Layer taxonomy

Layer	Primary owner	Config / command surface
Shell dedup	RTK	config/rtk-integration.json; wagents rtk doctor, wagents rtk sync, wagents rtk gain
Session pruners	OpenCode DCP	config/opencode-dcp.jsonc → ~/.config/opencode/dcp.jsonc; OpenCode /dcp stats
Cross-harness proxy	None (gated)	Research compare: Headroom vs Sleev vs LeanCTX
MCP schema tax	MCPHub harness	config/mcp-registry.json; MCPHub § control plane
Code reads	Policy-first	Narrow reads, ripgrep; symbol MCPs only if review shows pain
Standing context	instructions/global.md + skill descs	Scoped rules (.claude/rules/), on-demand skill bodies
Docs / maintainer hub	This page + AGENTS.md	/harness-config/token-efficacy/
Landscape tracking	Research journal	/research track token-oss-landscape (quarterly)

One-tool-per-layer rule

1. One primary tool owns each layer at a time.
2. Measure before stacking: run uv run wagents rtk gain --graph and review OpenCode DCP logs/stats (~/.config/opencode/logs/dcp/).
3. Overlap checks only where layers differ (e.g. RTK shell dedup vs LeanCTX — verify no double rewrite).
4. Repo hooks first: fleet safety hooks from config/hook-registry.json run before RTK projections when both apply.

RTK (shell layer)

RTK (Rust Token Killer) deduplicates shell command output before it enters the model context. Repo integration is doctor-verified and dry-run by default.

# Readiness across harness tiers
uv run wagents rtk doctor --format json

# Preview init commands (default)
uv run wagents rtk sync --dry-run --platforms claude-code,cursor,opencode,codex,gemini-cli,github-copilot

# Live apply (explicit; disables RTK telemetry for child processes)
RTK_TELEMETRY_DISABLED=1 uv run wagents rtk sync --apply --platforms claude-code,cursor,opencode,codex,gemini-cli,github-copilot

# Savings baseline / history
uv run wagents rtk gain --graph
uv run wagents rtk gain --history

Ownership boundaries:

• Policy SSOT: config/rtk-integration.json
• RTK owns local hooks, local RTK.md, and ~/.config/opencode/plugins/rtk.ts
• Not in opencode.json plugin array
• Not @RTK.md in instructions/global.md, AGENTS.md bridges, or generated Copilot instructions

Supported harness modes (see policy map): full-hook (Claude, Cursor, Gemini), OpenCode plugin, Codex prompt-rules, Copilot deny-suggest, Grok shim (planned).

DCP (session layer)

OpenCode Dynamic Context Pruning compacts in-session tool output and history. Repo canonical config:

• Source: config/opencode-dcp.jsonc
• Live: ~/.config/opencode/dcp.jsonc (synced via scripts/sync_agent_stack.py)

Model-neutral by default — do not add compress.modelMaxLimits or compress.modelMinLimits unless the maintainer explicitly requests per-model limits (AGENTS.md §2.3).

Tune thresholds only when log review (openspec/changes/token-efficacy-program/ Wave 4) shows compaction pain or threshold mismatch.

MCPHub (MCP layer)

MCP tool schemas are a major context tax. Prefer connecting harnesses to the harness MCPHub group rather than projecting every server to every client.

config/mcp-registry.json

# Edit SSOT
# Regenerate MCPHub settings + sync projections
uv run python scripts/sync_agent_stack.py --apply --targets repo

See mcp-registry for group definitions and MCP overview for MCPHub endpoints. MCP compressor or registry-split strategies require /research + /host-panel before any pilot install.

Standing context (instruction layer)

Always-loaded budget (approximate):

Component	Tokens	Loading
global.md	~980	Always
Skill descriptions	Varies	Always
Scoped rules	~0 until path match	Conditional
Skill bodies	~12k each	On-demand

Trim candidates come from /research + /review standing-context audits — not ad-hoc instruction bloat. Keep user-invocable skills in the / menu; hide auto-invoke convention skills (user-invocable: false).

Decision gates

Install or enable a new token tool only if the gate passes:

Category	Install only if
Session proxy	Compare winner + no DCP regression + explicit approval
MCP compressor	MCP strategy (R2) resolved + single-server pilot approved
Code MCP	Standing-context review shows Read-heavy pain + compare winner
Claude-only pruner	Compare winner for Claude layer + user sign-off
RTK fleet apply	wagents rtk doctor ok + maintainer runs --apply
DCP tune	DCP log/stats evidence + model-neutral guardrails preserved

Workflow

1. Baseline: wagents rtk doctor, wagents rtk gain --graph, OpenCode /dcp stats
2. Research: category compare matrices (read-only; no installs in recommendations)
3. Apply: RTK sync, instruction trims, or DCP tune — one layer at a time
4. Validate: re-run gain + DCP stats; wagents validate; docs regenerate

uv run wagents rtk doctor --format json
uv run wagents validate
uv run wagents docs generate --no-installed
uv run python scripts/sync_agent_stack.py --apply --targets repo

Related

Harness Config hubsync-manifest, mcp-registry, tooling-policy.

mcp-registryMCP groups including harness.

sync-manifestDCP and RTK projection surfaces.

HooksFleet hooks run before RTK when both apply.

AGENTS.md §5Canonical token budget and efficacy summary.

OpenSpec changetoken-efficacy-program proposal, design, validation.