TokenFlow

TokenFlow is a production-grade, provider-agnostic AI Execution Scheduler and Traffic-Shaping Proxy designed to run seamlessly between autonomous coding agents (such as Claude Code, Aider, Cline, Antigravity, and Cursor) and upstream model providers (Anthropic, OpenAI, Gemini, etc.).

Instead of optimizing for raw, bursty throughput that leads to rate-limiting failures (HTTP 429) and session starvation, TokenFlow schedules and paces AI resources (tokens, costs, request slots, and context window limits) to guarantee continuous, uninterrupted agent progress.

+-----------------------------------------------------------+
|                    Agent / User Prompt                    |
+-----------------------------------------------------------+
                              |
                              v
+-----------------------------------------------------------+
|                    TokenFlow Scheduler                    |
|                                                           |
|   +-------------------+             +-----------------+   |
|   |   Local Scanner   |  Priors     | Dynamic Pacing  |   |
|   |   (Zero-Token)    |------------>| Queue (DRR/WFQ) |   |
|   +-------------------+             +-----------------+   |
|             |                                |            |
|             +------------+     +-------------+            |
|                          |     |                          |
|                          v     v                          |
|   +---------------------------------------------------+   |
|   |         Closed-Loop PID Adaptive Controller       |   |
|   +---------------------------------------------------+   |
+-----------------------------------------------------------+
                              |
                              v
+-----------------------------------------------------------+
|                 Provider Routing Proxy                    |
+-----------------------------------------------------------+
         /                    |                    \
        v                     v                     v
 +-------------+       +-------------+       +-------------+
 |  Anthropic  |       |   OpenAI    |       |  Local LLM  |
 +-------------+       +-------------+       +-------------+

Key Features

• Closed-Loop PID Control: Dynamically adjusts token allocation rates and queuing delays using a mathematical Proportional-Integral-Derivative (PID) controller. This shapes traffic, eliminating HTTP 429 rate limit exceptions before they happen.
• Weighted Fair-Share Queueing (DRR Scheduler): Groups jobs by terminal session and splits token bandwidth fairly using a Deficit Round Robin (DRR) policy. If you run multiple agents in different tabs, one heavy session won't starve other active agent sessions.
• Adaptive Estimation Calibration: Learns from transaction execution errors in real-time. If the agent's actual consumption is significantly lower than estimated (e.g., fast failures or small replies), the scheduler scales down enqueued allocations, allowing more queries to pack into the active rate window.
• Zero-Token Repository Scanner: Recursively compiles Lines of Code (LOC), directory depth, file counts, and dependency imports locally using a high-speed AST/metadata parser. It sends a highly compressed summary matrix under 200 tokens, avoiding sending whole directory trees to LLMs.
• Context Window Governance & Deflation: Monitors context window pressure ($P_c$). When the threshold is exceeded (default: 80%), it automatically compresses intermediate message logs into a system-guided summary while keeping recent turns intact.
• Automatic Prompt Caching (90% Cost Saving): Automatically scans outgoing Claude (Anthropic) requests. If the input is large, it injects cache breakpoints (cache_control: { type: "ephemeral" }) into system prompts and sliding message history. This triggers Claude's prompt caching on subsequent turns, saving you up to 90% in token costs.
• Zero-Config Interceptor Runner (tf exec): Allows any terminal agent (like Claude Code) to run scheduled out-of-the-box. TokenFlow starts a local proxy, injects base URL redirection overrides into the environment, and spawns the agent cleanly.
• Autopilot Installation & Skill Injector: The global installer automatically appends shell aliases to your profiles and detects which of the 60+ supported coding agents are installed on your machine, injecting the custom TokenFlow SKILL.md directly into their configurations.
• Local LLM Offline Fallback: Automatically senses internet drops or budget ceilings. If a local Ollama instance is active (http://localhost:11434), it converts standard OpenAI/Anthropic stream formats dynamically and fails over to local models (like llama3) offline, keeping your agent executing.
• Dual-Mode Visualizer:
  • Terminal Status Bar HUD: Displays a sticky, real-time status line at the bottom of your terminal while running ([TokenFlow HUD] Queue: 1 | Multiplier: 0.46 | Cost: $0.12), showing queue sizes and spending metrics dynamically without corrupting the agent output.
  • Interactive Web Dashboard: Serves a beautiful glassmorphism control panel at http://localhost:8080/dashboard where you can pause/resume the scheduler queue, dynamically adjust TPM/RPM and budget limits, configure standard/premium model mappings, and inspect local session logs.

Supported Agents

TokenFlow automatically injects global skill definitions into 60+ popular agents upon installation, including:

• Claude Code (~/.claude/skills/)
• Cline / Roo Code (~/.agents/skills/ / ~/.roo/skills/)
• Cursor (~/.cursor/skills/)
• Windsurf (~/.codeium/windsurf/skills/)
• GitHub Copilot (~/.copilot/skills/)
• Continue (~/.continue/skills/)
• Antigravity & Antigravity CLI (~/.gemini/antigravity/skills/)
• And 50+ other agent CLI systems.

Getting Started

1. Interactive Installation (Recommended)

To launch the interactive setup wizard directly in your terminal (using npx to run without global binary installation warnings):

npx @peler1nl1kelt0s/tokenflow

This parses your active environment, checks your PATH for installed coding CLI agents (claude, aider, etc.), and allows you to selectively choose which commands to alias and which agent directories to configure with the TokenFlow skill.

Note: Restart your terminal or run source ~/.zshrc to activate the shell aliases immediately.

2. Basic Usage (Zero-Config)

To run your favorite terminal agent under TokenFlow's adaptive pacing queues:

# Wrap Claude Code
claude

# Wrap Aider
aider --git

These run the commands wrapped through the tf exec interceptor proxy automatically.

3. Manual Server Execution

Start the reverse proxy server on a custom port with specific TPM and RPM quotas:

tf start --port 8080 --tpm 40000 --rpm 3

4. Running a Local Scan

Scan any directory locally to generate high-speed complexity and file import telemetry:

tf scan ./src

5. Installing Local Workspace Skills

To explicitly add the TokenFlow custom skill block to a specific project directory (e.g., to share with your team in Git):

tf add-skill --dir .agents/skills

6. Accessing the Dashboard

Open your browser and navigate to the local dashboard to monitor real-time enqueues, uptime, and multiplier scaling values:

http://localhost:8080/dashboard

7. Config & Model Custom Mappings

TokenFlow automatically creates a persistent configuration file at ~/.tokenflow/config.json upon startup. It comes preconfigured with the latest active API models:

• Anthropic Claude: Maps complex reasoning to claude-sonnet-5 and simple/selamlaşma tasks to claude-haiku-4-5.
• OpenAI GPT & Reasoning: Maps complex coding to gpt-5.6-sol / o1 and simple tasks to gpt-5.6-luna / o1-mini.

You can easily change these mappings, register your own custom fine-tuned models, or set a USD budget limit directly in the settings tab of the Web Dashboard.

8. Dry-Run Simulation Mode

Want to test your autonomous agent loops completely free of charge? Use the --dry-run flag:

tf exec --dry-run "npx @anthropic-ai/claude-code"

TokenFlow will intercept all API calls locally, streaming realistic mock completion chunks with natural pacing, letting you validate agent logic without spending money.

9. Context-Aware Prompt Summarization

When token limits are approaching, TokenFlow's context compression engine dynamically summarizes historical turns. If a local Ollama service (llama3) is running, it executes a fast local summarization of early messages to condense history into a single cohesive system memory instruction, ensuring agent context memory remains intact.

10. Compact Dashboard HUD

Click Compact HUD in the Web Dashboard to toggle the browser dashboard into a mini floating window format. Shrink it, pin it to a screen corner, and monitor budgets and PID scale multipliers side-by-side with your code editor.

CLI Telemetry Report Output

When you quit a wrapped agent execution, TokenFlow prints a rich ASCII report summary directly in your shell:

=========================================
      TokenFlow Session Telemetry       
=========================================
Uptime:             45s
Total Requests:     4
Actual Tokens:      1,532
Estimated Tokens:   8,500
Tokens Saved:       6,968
Adaptive Scale Mult: 0.46
=========================================

Project Structure

tokenflow/
├── bin/
│   └── tf.js                  # CLI global bin executable
├── src/
│   ├── cli/
│   │   ├── index.ts           # Commander CLI registry
│   │   └── exec.ts            # Redirection process spawner
│   ├── core/
│   │   ├── limiter.ts         # Sliding window TPM/RPM rate limiter
│   │   ├── scheduler.ts       # Priority execution queue
│   │   ├── pid.ts             # Math feedback PID loop
│   │   └── contextManager.ts  # Pressure deflation engine
│   ├── estimators/
│   │   └── repoScanner.ts     # Local dependency import mapper
│   └── proxy/
│       ├── router.ts          # Complexity routing manager
│       ├── server.ts          # Express reverse proxy server
│       └── dashboard.html     # Glassmorphism HTML page
└── tsconfig.json

Contributing

TokenFlow is open-source software licensed under the Apache 2.0 License. We welcome contributions to provider adapters, routing policies, and control loop tuning.

To run the Vitest unit test suite locally:

npm run test