token-flux

Token-saving and quality-boosting toolkit for AI coding agents.

Install it in a repository, initialize it once, and your agent gets:

• a compact project map before it reads source files
• risk-aware context selection for each task
• compressed terminal output for noisy commands
• prompt and response compression rules
• MCP tools for agents that support MCP
• boost prompts for weaker or cheaper models
• verification and mistake-memory rails

The goal is simple: spend fewer tokens when token cost matters, and get better coding results when using lower-cost models.

Install

npm install -g token-flux

Or run without global install:

npx token-flux init

Initialize In A Repo

From your project root:

token-flux init

Non-interactive setup:

token-flux init --yes

This writes repo-local agent instructions and support files. Depending on selected adapters, it may create files such as:

• AGENT.md
• CLAUDE.md
• .agent-boost/config.json
• .agent-boost/anatomy.md
• .agent-boost/context-index.json
• .agent-boost/cerebrum.md
• .agent-boost/scripts/
• .mcp.json

Choose Operating Mode

token-flux has three operating modes.

token-flux mode set saver
token-flux mode set boost
token-flux mode set both
token-flux mode status

Use saver when token cost matters most.

• Best for strong or expensive models.
• Enables prompt compression, output-style compression, CLI proxy, context router, model router, MCP setup, and project scan.
• Focus: fewer tokens while keeping correctness.

Use boost when result quality matters most.

• Best for weaker, cheaper, or local models.
• Enables expert prompt enhancement, production gates, scoring, retry prompts, codemap, lessons, and verifier.
• Focus: stronger coding behavior, not maximum token saving.

Use both when you want adaptive behavior.

• Default choice for most users.
• Combines quality rails and token-saving tools.
• Useful when you switch between models.

Token-Saving Levels

These are response-compression levels, not operating modes:

• light / lite: concise but quality-first
• full: compact and complete, default
• ultra: aggressive prose compression while preserving code details

Use them in session instructions:

token-flux session-start --level light
token-flux session-start --level full
token-flux session-start --level ultra

Important: token-flux should never compress away routes, API contracts, auth/security checks, tests, errors, file paths, commands, or identifiers.

Recommended Workflow

For a normal coding task:

token-flux context "fix login session timeout bug"

Then open only the files listed by the context result.

Before reading many files:

token-flux budget src/auth/session.ts src/auth/session.test.ts

For noisy commands:

token-flux proxy "npm test"
token-flux proxy "git diff"
token-flux proxy "npm run build"

Before finishing:

token-flux verify

Check savings:

token-flux token-status

Minimal Context Router

The most important token-saving command is:

token-flux context "<task>"

It reads .agent-boost/context-index.json and returns a small task packet:

• likely relevant files
• support/test files
• token estimate
• task intent
• risk score
• changed files
• next steps

Detail levels:

token-flux context "review auth changes" --detail minimal
token-flux context "review auth changes" --detail standard
token-flux context "review auth changes" --detail full

Use minimal first. Move to standard or full only when risk or uncertainty requires it.

Seed changed files manually:

token-flux context "review payment refactor" --changed src/payments/api.ts,src/payments/api.test.ts

JSON output:

token-flux context "fix checkout bug" --json

Project Scan

Refresh the project intelligence files:

token-flux scan

This generates:

• .agent-boost/anatomy.md: readable file map for agents
• .agent-boost/context-index.json: compact machine index with roles, risk scores, communities, public entrypoints, and large files
• .agent-boost/cerebrum.md: mistake memory file, created if missing

Run scan after large refactors or when many files are added.

MCP Integration

For MCP-aware agents:

token-flux mcp install

This updates .mcp.json with a local token-flux MCP server.

Available MCP tools:

• get_minimal_context: same purpose as token-flux context
• check_budget: estimate token cost before reading files
• compress_prompt: compress long prompts while preserving code blocks

Manual server command:

token-flux mcp serve

Recommended MCP rule for agents:

Call get_minimal_context first. Use detailLevel="minimal" until risk requires more.

Boost Agent Workflow

Use boost when using a lower-cost model and quality matters more than token count.

token-flux boost "add pagination to the users API and UI"

This builds an enhanced prompt with:

• task type detection
• domain detection
• production gates
• model-specific weakness fixes
• relevant codemap/anatomy context
• relevant lessons

Score a model response:

token-flux score "<model response>"

Build a retry prompt if the response is weak:

token-flux retry --original "<original task>" --response "<bad response>"

Prompt Compression

Compress long task prompts:

token-flux compress "please help me fix this long issue description..."

With a level:

token-flux compress --level ultra "long prompt here"

JSON output:

token-flux compress --json "long prompt here"

The compressor preserves fenced code blocks and technical details.

CLI Proxy

Wrap commands whose output would waste context:

token-flux proxy "npm test"
token-flux proxy "pytest"
token-flux proxy "git diff"
token-flux proxy "git log"
token-flux proxy "npm run build"

The proxy keeps the important parts:

• failing test names
• error messages
• relevant stack frames
• build failures
• lint/type errors
• diff hunks
• summaries and counts

It suppresses repetitive passing output, long listings, and noisy logs.

Generated Agent Rules

token-flux install injects token-saving rules into supported agents:

token-flux install

Supported adapters include:

• generic
• claude-code
• cursor
• cline
• aider
• vscode
• antigravity
• opencode

Install for a specific tool:

token-flux install --tool claude-code

Commands

Setup:

token-flux init
token-flux install
token-flux uninstall

Modes:

token-flux mode set saver
token-flux mode set boost
token-flux mode set both
token-flux mode status

Token saving:

token-flux scan
token-flux context "<task>"
token-flux budget <files...>
token-flux compress "<prompt>"
token-flux proxy "<command>"
token-flux session-start --level full
token-flux token-status
token-flux dashboard
token-flux mcp install
token-flux mcp serve

Quality boost:

token-flux boost "<task>"
token-flux score "<response>"
token-flux retry --original "<task>" --response "<response>"
token-flux codemap
token-flux verify

What To Tell Your Agent

After setup, make sure your coding agent follows this workflow:

1. Run token-flux context "<task>" before broad source reads.
2. Read .agent-boost/cerebrum.md before fixes.
3. Open only the exact source files needed for correctness.
4. Use token-flux proxy for noisy commands.
5. Never omit routes, API contracts, auth/security checks, tests, errors, file paths, commands, or identifiers.
6. Verify before calling the task done.

If MCP is available:

1. Call get_minimal_context first.
2. Use detailLevel="minimal" by default.
3. Call check_budget before opening many files.

Cleanup

Remove token-flux files from a repo:

token-flux uninstall

Uninstall the global package:

npm uninstall -g token-flux

License

MIT