TokenReducer Research experiment
545/545 passed

Copilot-native / Experimental

Less corpus in the parent.
More room for judgment.

Keep your selected coordinator. Give a separate worker the source-reading job. Return compact evidence, or pass --target to write generated code to disk without streaming its body into the parent's conversation.

Inspect the 3D flow Read the README Set it up
Verification
545/545
0 failed / 0 skipped
Read gate
350
Actual lines in the read window
Compact answer
4,096
UTF-8 bytes, not tokens
Work order
1 MiB
Default, including JSON overhead
scripted-worker / illustrated flowNOT A LOG

# The coordinator keeps its selected model.

[parent] requests a large file read

[gate] actual window exceeds 350 lines

[gate] deny with delegation guidance

[skill] question + explicit paths + root

[worker] fresh CLI process; piped stdin JSON

[worker] full source processed in its own context

[check] reported model + bounded final output

[parent] compact answer; with --target: {written, bytes, model}

The gate nudges; the skill routes work. This is not an automatic hook-to-worker handoff.

01 / Interactive WebGL illustration

A separate context, not a security sandbox.

The parent's cyan core stays on the left. The source corpus sits off to the right, feeding a green worker. Only a compact result travels back. The shapes illustrate the mechanism, not a live trace, token count, or quality measurement.

Invented geometry / No files or models involved

Static illustration. 3D is not enabled; no CDN request has been made.

Context flowILLUSTRATIVE

SOURCE -> WORKER -> COMPACT RETURN

The complete source is still processed in the worker's context.

Parent model: unchanged

Static diagram / 3D optional
Parent coordinator

Your selected model. Receives a compact result and keeps the judgment.

Full source corpus

Still read and processed in the worker. It is not eliminated by delegation.

Isolated worker context

A fresh CLI process, not an OS sandbox. The grid barrier represents the read gate.

Compact return

An anchored answer or file confirmation. Review and follow-ups still cost context.

Static first: Three.js loads only when you enable 3D. A failed CDN load or WebGL renderer leaves an explicit error and this static illustration. All controls work from the keyboard; reduced-motion preferences keep the scene still. Dependency: Three.js 0.170.0 (r170), pinned on jsDelivr.

02 / Architecture & boundaries

Skills route. The gate nudges. Scripts enforce.

The parent is your existing coordinator. A scripted worker is a new Copilot process with one explicit work order. Native named agents are also available, but their instruction-only path does not inherit the scripted guarantees or accounting below.

Execution flow & context placement

On narrow screens, scroll the diagram horizontally or use its written caption.

From a large read to a bounded answer

A gate nudge followed by a separate scripted workerThe parent requests a read. A read window over 350 lines receives denial and guidance. The skill invokes a script with explicit input. Full file bytes enter the worker through stdin. A validated compact answer returns to the parent. PARENT / SKILLREAD GATESCRIPT / TRANSPORTSEPARATE WORKER 1. Read request WINDOW > 350 LINES 2. Denial + guidance 3. Skill invokes script with explicit inputs 4. File bytes via stdin 5. Script validates model and bounded final output
1. The parent requests a read. 2. The gate checks the real line window and returns guidance if it is oversized. 3. The skill routes a separate scripted job. 4. Source bytes enter only the child work order. 5. A model-verified, bounded result returns. The hook does not automatically execute the worker.

Full-parent ingestion versus scripted delegation

Two context layouts with worker input counted separatelyThe comparison baseline places full source in the parent. The scripted path gives the parent a compact return while the full source still occupies the separate worker's context. Shapes are schematic and not proportional measurements. FULL-CORPUS BASELINESCRIPTED DELEGATION Parent: full source + taskAn ingestion baseline, not ideal search Parent: task + compact return Worker: complete source still processedSeparate context, not eliminated input Small reads and targeted search already exist.
Before: full corpus in the parent. After: compact evidence in the parent, full corpus in the worker. These shapes are schematic, not token allocations. The benchmark is not a comparison against the best targeted-search or small-read workflow.

Write the artifact; return the receipt

Generation to disk with confirmation-only stdoutThe parent supplies a specification, mandatory reference, and explicit --target path. A separate worker produces code. The script checks it and atomically publishes a file up to one MiB. With --target, the parent receives written, bytes, and model fields, not the generated body. EXPLICIT WORK ORDERSpec + mandatory referenceExplicit --target pathNo inherited transcript WORKER + SCRIPTValidate nonempty final codePrivate staging, atomic publish1 MiB file ceiling, including newline PARENT RECEIPT{written, bytes, model}Generated body stays on diskBounded review still costs context
Generation requires a specification and a reference. Pass --target explicitly for disk output and a JSON receipt; without it, stdout returns code capped at 4,096 UTF-8 bytes. The script validates the result before publication. Existing targets need --overwrite; conflicts or concurrent changes are refused. The JSON receipt is not a diff summary or a substitute for inspecting the generated code.

[01] BULK-READER

Question + explicit paths + root

The scripted reader defaults to claude-haiku-4.5. It answers a focused question about the supplied source, preserving useful file and line anchors. No inherited transcript.

[02] CODE-WRITER

Spec + mandatory reference

The scripted writer defaults to gpt-5.4-mini. Pass --target explicitly to write to disk and receive only {written, bytes, model}. Without --target, stdout returns code capped at 4,096 UTF-8 bytes. Stderr contains coarse metadata.

[03] MODEL CONTRACT

Only unavailability permits retry

An unavailable model may retry gpt-5-mini within a shared 120-second deadline. Missing or wrong reported model identity is an error: no returned answer, no published file, no fallback.

03 / Verification & test battery

What is exercised, what must hold, what remains unproven.

Original fixtures and a deterministic stub CLI test the contracts. These eight groups organize the walkthrough rather than report separate pass totals. Optional live checks are a separate, authentication-dependent path.

545/545 passed

Contract checks, not model-quality certification

npm test and npm run eval each reported: 545/545 passed; 0 failed; 0 skipped.

Node.js >=20 / No npm install
[01] HookDeterministic

Count the actual read window

Stimulus
Large reads, finite small ranges, EOF suffixes, oversized windows, ordinary calls, and the included Bash and PowerShell launcher paths.
Contract
The default gate is 350 lines, not 4,000 tokens. Count actual remaining or requested lines rather than accepting every offset/limit pair as bounded. Keep small windows usable. Pass ordinary calls through with an empty object so host permissions still apply.
Does not prove
The hook is not a universal output filter. Other tools and arbitrary programs can print large bodies. A host timeout is fail-open, and project hooks require workspace trust.

Hook tests

[02] TransportDeterministic

A fresh worker with verifiable model evidence

Stimulus
A stub CLI receives JSON work orders and returns JSONL containing valid responses, model-unavailable outcomes, missing or wrong model evidence, and attempted tool calls.
Contract
Use piped stdin, not -p, with a private temporary COPILOT_HOME. No inherited transcript, MCP, custom instructions, or remote export. tools: [] restricts actual tool availability; extra CLI denial kinds are exactly shell, write, and url. Reject tool attempts and invalid model evidence. Pass only environment-supported CLI authentication, never pasted secrets; clean transport and staging directories.
Does not prove
A stub does not certify every CLI or provider. Process isolation and tool restrictions are not a security sandbox or DLP boundary. Only model unavailability permits the fallback within the shared 120-second deadline.

Transport tests

[03] InputDeterministic

Explicit paths and complete byte budgets

Stimulus
Malformed flags and configuration; absent, escaping, directory, special, binary, or invalid-UTF-8 files; quoted names; oversized instructions; too many paths; and two large inputs with unique first and last anchors.
Contract
Accept UTF-8 regular files inside the root, up to 64 explicit paths. Contained input symlinks canonicalize; symlink escape fails. Count the full serialized JSON work order against the default 1 MiB ceiling, including labels, rules, and line numbers. Reject invalid inputs before invoking Copilot. Reader numbering preserves real lines and anchors; code references remain raw.
Does not prove
Containment and valid encoding do not make source instructions trustworthy. They do not guarantee a correct answer or resistance to every prompt injection.

Input tests / Fixture tests

[04] OutputDeterministic

Only a nonempty, bounded final result

Stimulus
Empty answers, empty or malformed fences, trailing explanations, unsafe controls, malformed Unicode, and ASCII or multibyte responses at the compact-output boundary.
Contract
Require a nonempty final result. Only code-writer strips whole-response fences, without rewriting raw indentation; bulk-reader does not strip fences. Enforce the 4,096-byte UTF-8 answer ceiling, not a character or token count. Withhold malformed responses. Errors must not forward a partial answer to parent stdout.
Does not prove
A compact, well-formed answer can still be wrong. Model verification checks transport evidence, not factual truth or complete symbol extraction.

Output tests

[05] GenerationDeterministic

Publish atomically; return a small receipt

Stimulus
Nontrivial generated stub code; a follow-up using the just-written file in a fresh worker; exact 1 MiB boundaries including the newline; existing or concurrently changed targets; missing parents; traversal; symlinks; and hardlinks.
Contract
With an explicit --target, its parent must exist. Existing files require --overwrite; conflicts and concurrent changes are refused. No symlink target. Publish atomically from private staging, with private Unix permissions for new files. Include the published newline in the 1 MiB limit. Only with --target, return {written, bytes, model} instead of the generated body. Without it, stdout code is capped at 4,096 UTF-8 bytes.
Does not prove
Safe publication is not a code review. Bounded inspection and execution still cost time and tokens. No zero-parent-token claim is made for reading generated code.

Generation regressions / Publication and output tests

[06] AccountingDeterministic

A reproducible proxy, with visible overhead

Stimulus
Original deterministic fixtures of at least 700 lines, unique first/last anchors, an executable ESM reference, and labeled nontrivial stub generation across single-file, multifile, and disk-output scenarios.
Contract
Keep fixtures complete and reproducible. Both benchmark sides include invocation text, skill text, and the fixed 1,024-character delegation allowance. Compare full-corpus parent ingestion with the scripted reply and coarse metadata. Include the generation review allowance and keep worker processing distinct. Display ceil(characters / 4); compute percentages from unrounded character totals.
Does not prove
No tokenizer, invoice, model quality, or native-agent result is measured by the stub. The baseline is not an ideal targeted-search or small-read workflow.

Accounting tests / Benchmark implementation

[07] InstallerDeterministic

Install owned assets, not a workspace takeover

Stimulus
Fixture project and personal installs; paths containing spaces, apostrophes, dollar signs, and semicolons; repeated installs; unrelated sentinel files; conflicts; and symlinked installation destinations.
Contract
Copy only owned skills, hooks, and agents. Preserve unrelated files. Preflight conflicts and require --overwrite. Refuse symlinked destinations. Personal hook paths are absolute and quoted. Exercise installed launchers as well as source templates.
Does not prove
A fixture install cannot establish user trust, certify every operating system or CLI version, or guarantee that the host has enabled project hooks.

Installer tests

[08] LiveVerified live

Verified anchors and generated-module syntax

Stimulus
The optional npm run eval:live was executed on using Copilot CLI 1.0.84-2, supported authentication, and available models. It exercised exact first/last-anchor requests and generation to disk.
Verified output
Reported successful models: claude-haiku-4.5 and gpt-5.4-mini. LIVE verified: 2 exact first/last-anchor requests; 13,998-byte generated ES module written and syntax-checked.
Does not prove
This is a scoped anchor/output and syntax check, not general code-quality or billing validation. Parent generated-body tokens were not measured. These real-model checks do not turn the separate STUB accounting figures into live savings.

Live evaluation script

04 / Reproducible accounting

Count what reaches the parent. Keep the worker on the ledger.

Character-based estimates compare full-corpus parent ingestion with scripted delegation. They do not measure inference tokens, model pricing, answer quality, or total task cost. The native named-agent path is not represented.

Current STUB accounting

Not a live-model run

npm run benchmark completed successfully. These current verified totals include the updated skill text, which increases counted overhead compared with earlier snapshots. Re-run against the exact version you use. Read the saved numeric results.

Current deterministic STUB run, verified 12 September 2026. Parent and worker columns are character-based token estimates.
Scripted scenarioFull material in parentDelegated parent totalWorker input estimateLower parent-input proxyParent footprint
One large fileScripted bulk-reader30,91585831,58697.23%
Several source filesScripted bulk-reader62,45589364,46098.57%
Generate to diskScripted code-writer17,7471,46113,90391.77%

Full-parent material Delegated parent total. The complete input is still processed by the worker.

One explicit estimator

Displayed estimates use ceil(characters / 4). Percentages use unrounded character totals, not the rounded displayed estimates. This is not a tokenizer.

Include the delegation overhead

Both sides include invocation text, skill text, and the fixed 1,024-character delegation allowance. The scripted side also counts its compact reply and coarse metadata. Worker input is not eliminated.

Keep code review in the comparison

The current generator fixture wrote 13,896 bytes to disk. Its parent total reserves 512 estimated parent tokens for review. Inspection is not free; live review-token consumption is not measured here.

Character arithmetic, not a savings predictor.

Enter two explicit character totals. Include any delegation overhead yourself. This calculator does not predict answer length, choose a model, or estimate a bill. Its defaults are illustrative, not benchmark inputs.

05 / Setup & reproduction

Install deliberately. Delegate from your existing coordinator.

Use Node.js >=20 and an authenticated Copilot CLI for worker execution. Runtime and evals use only Node's standard library. No npm install is needed.

  1. Get the source and install owned assets.

    The installer copies only TokenReducer's skills, hooks, and agents. Replace the example workspace path; quote paths with spaces. Unrelated files remain intact. Conflicts require --overwrite.

  2. Review, trust, and restart the CLI.

    Review the installed hooks before trusting the folder. Restart Copilot CLI, then check /skills list and /skills info bulk-reader. Project hooks need workspace trust.

  3. Keep the parent model selected.

    Ask the skill to use its scripted worker with explicit inputs. Do not switch with /agent and call that delegation. Native named agents remain instruction-only alternatives, without the scripted guarantees or measured accounting.

Project install
git clone https://github.com/brianbaldock/TokenReducer.git
cd TokenReducer
node scripts/install.mjs --project /path/to/workspace
Use a personal install instead
node scripts/install.mjs --personal

Run from the TokenReducer source directory. Personal hook paths are absolute and quoted. Both Bash and PowerShell launchers are included.

Contracts

npm test

Deterministic regression checks.

Scenarios

npm run eval

Offline fixture workflows.

Accounting

npm run benchmark

Reproducible parent-input proxies.

Optional live

npm run eval:live

Requires supported authentication and available models.

06 / Research lineage

Original implementation. Visible credit.

This experiment builds on others' research about model choice, context selection, and agent interfaces. These works motivate the questions; they do not prove TokenReducer's results.

FrugalGPT

TMLR, 2024 / Model cascades

Explores LLM cascades and cost-quality tradeoffs.

Distinction: Task-specific worker defaults are not FrugalGPT's learned cascade strategy.

RouteLLM

arXiv:2406.18665 / Routing

Studies stronger/weaker model routing using preference data.

Distinction: This project does not train a router or reproduce its quality-cost curves.

AutoMix

arXiv:2310.12963 / Verification

Explores self-verification and model mixing.

Distinction: Deterministic transport checks are not AutoMix's answer-verification algorithm.

LLMLingua

arXiv:2310.05736 / Compression

Compresses prompts to reduce inference overhead.

Distinction: TokenReducer routes full source and returns compact evidence; it does not implement token-level prompt compression.

LongLLMLingua

arXiv:2310.06839 / Long context

Studies question-aware long-context compression.

Distinction: It informs a context-selection question, not this implementation's mechanics or accounting.

Lost in the Middle

TACL, 2024 / Position effects

Shows that information position can affect long-context performance.

Distinction: It motivates care with context, not a claim of better reasoning here.

SWE-agent

arXiv:2405.15793 / Agent interfaces

Examines agent-computer interfaces for software engineering.

Distinction: Tool boundaries are a design choice here; the project does not implement SWE-agent.

Aider repository map

Aider documentation / Code context

Provides a compact repository representation to focus code context.

Distinction: Explicit files and worker answers are not Aider's repository map or symbol-graph algorithm.

Building Effective Agents

Anthropic / Workflow patterns

Describes practical routing and orchestrator-worker arrangements.

Distinction: A useful design reference, not a certification of this runtime.

Recursive Language Models

arXiv:2512.24601 / Decomposition

Explores programmatic access to large contexts and recursive model calls at inference time.

Distinction: TokenReducer uses bounded one-job workers, not that algorithm or recursive training.