tokenkiller

# TokenKiller (Universal Throttling)

## Goal

Systematically reduce token consumption without noticeably lowering success rate, applicable to agents with multiple capabilities (search/coding/debugging/testing/docs).

## Task Complexity Assessment

Before setting budgets, assess task complexity:

| Complexity | Criteria | Tool Budget | Output Budget |
|------------|----------|-------------|---------------|
| Simple | Single file modification, single-point localization, clear requirements | ≤3 calls | ≤50 lines |
| Medium | Across 2-3 files, needs simple exploration, relatively clear requirements | ≤6 calls | ≤120 lines |
| Complex | Cross-module refactoring, multi-step debugging, unclear requirements | ≤10 calls | ≤200 lines |

**Extension Mechanism (Soft Warning)**: When budget is about to run out but task is incomplete:
1. Output warning: `[TokenKiller] Budget running low, current progress X/Y, remaining work: ...`
2. Continue execution, but switch to more conservative strategy
3. User can interrupt or request more detailed output at any time

## Default Working Mode (Balanced)

### Global Hard Rules (Must Follow)

- **Goal First, Evidence Later**: State the goal in one sentence (L0) first, then decide if evidence is needed (L2/L3).
- **Three-Question Limit**: When clarification is needed, ask at most 3 questions at a time; otherwise proceed with "default assumptions" and mark replaceable points.
- **Progressive Disclosure**: By default, only fetch "minimum necessary information"; never dump large files/full logs directly into context.
- **Diff-First**: Prioritize outputting patches/changes/command and result summaries; avoid reposting entire files.
- **Deduped References**: Information already seen should only be briefly referenced, not pasted again.

### Budget Gate (Budget + Gate)

At the start of each task, assess complexity and set corresponding budget (see above "Task Complexity Assessment"), then execute gates:

- **Tool Call Budget**: Set by complexity (Si...

# tokenkiller

Reduce token usage for agent workflows (budgets, gating, progressive disclosure, dedupe).

## What it is

TokenKiller is a lightweight skill/policy to systematically reduce LLM token usage **without noticeably lowering success rate**. It is designed for multi-step agent workflows such as:

- search / exploration
- coding / refactoring
- debugging / troubleshooting
- testing / verification
- docs / summarization

## How it works

Core mechanisms:

- **Dynamic budgets**: Assess task complexity first, then apply appropriate budget (simple/medium/complex)
- **Progressive disclosure**: pull only the minimum necessary context (avoid big-file/log dumps)
- **L0-L3 information layers**: Start with goal (L0), constraints (L1), evidence (L2); only pull full content (L3) when necessary
- **Diff-first outputs**: prefer patches and deltas over full-file reposts
- **Deduped evidence**: never paste the same content twice; reference it briefly instead
- **Token self-check**: periodic review of token consumption patterns
- **Multi-skill collaboration**: works alongside other skills as a constraint layer

## Key Features

### Dynamic Budget Mechanism

| Complexity | Criteria | Tool Budget | Output Budget |
|------------|----------|-------------|---------------|
| Simple | Single file, clear requirement | ≤3 calls | ≤50 lines |
| Medium | 2-3 files, some exploration | ≤6 calls | ≤120 lines |
| Complex | Cross-module, multi-step, unclear | ≤10 calls | ≤200 lines |

When budget runs low but task incomplete, a warning is issued and strategy shifts to more conservative mode.

### L3 Pull Triggers

Only pull full content (L3) in these scenarios:
- Code modification requiring exact indentation/format
- Config debugging with interdependent settings
- Error analysis needing complete stack trace
- User explicitly requests full content

### Multi-Skill Priority

- Functional skills (pdf, xlsx, etc.) take precedence
- TokenKiller applies as a constraint layer during output
- User r...