Skip to main content
Glama

Token Runway šŸ›«

PyPI version Python 3.8+ License: MIT MCP

Real-time token runway & rate-limit awareness for AI agents.
Give LLMs the self-awareness to weigh whether their actions are justified before exhausting your quotas.


The Problem: Quota-Blind Agents

Modern coding agents (Claude Code, Cursor, Antigravity, Windsurf) operate blind to their own resource limits. An agent will happily fan out five parallel subagents, dump 100,000 tokens of file contents into context, or run recursive test loops when you have 2% of your 5-hour quota remaining and 15 minutes until reset.

The result? Unplanned HTTP 429 rate-limit lockouts, stalled workflows, and burnt monthly budgets.

Related MCP server: agent-token-budget-mcp

The Solution: Token Runway

Token Runway is a pure-Python, zero-dependency Model Context Protocol (MCP) server and CLI tool. It aggregates live consumption metrics from your local developer tools and exposes them directly to LLMs through MCP tools, resources, and self-governance prompts.

ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│                   AI Coding Agent                      │
│      "Should I launch 5 subagents for this task?"      │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”¬ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜
                           │ calls assess_action()
                           ā–¼
ā”Œā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”
│                  Token Runway MCP                      │
│   • Claude 5-hour: 96% used (Resets in 18 min)         │
│   • Verdict: PAUSE_OR_DOWNGRADE                        │
│   • Strategy: "Use targeted ripgrep instead of loading │
│               full files. Window resets in 18m."       │
ā””ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”€ā”˜

Supported Providers

Provider

Harvester Source

Metrics Exposed

Setup Command

Anthropic Claude

~/.claude/ credentials or CLAUDE_CODE_TOKEN

5-Hour Current utilization %, Weekly 7-Day %, countdowns

claude (or CLAUDE_CODE_TOKEN=...)

GitHub Copilot

GitHub CLI (gh api /copilot_internal/user)

Chat Monthly %, Completions %, Plan tier, reset date

gh auth login

Google Gemini

Antigravity CLI (agy)

Flash/Pro 5-Hour %, Flash/Pro Weekly %, Argon Weekly %

agy in $PATH

Antigravity

Antigravity CLI (agy)

Claude & GPT models 5-Hour %, Weekly %

agy in $PATH

Google Colab

Colab CLI (colab usage)

Compute unit balance, burn rate/hr, active runtimes

colab in $PATH

OpenRouter

OpenRouter Key API

Credit limit, spend balance, rate limit interval

OPENROUTER_API_KEY=...

OpenAI API

OpenAI Models API

Model tier access, key validation

OPENAI_API_KEY=...


Authentication & Provider Setup

Token Runway is designed around a Zero Manual Configuration philosophy: it automatically piggybacks on the tools and sessions you already use every day. You don't need to generate or paste API keys.

1. Anthropic Claude

  • Automatic Discovery: If you have Claude Code installed, simply log in once:

    claude

    Token Runway automatically discovers your OAuth token in ~/.claude/.credentials.json.

  • Manual / Headless / CI: If running in an environment without ~/.claude/, pass your token via the CLAUDE_CODE_TOKEN environment variable:

    export CLAUDE_CODE_TOKEN="your-oauth-token"

    Or in your MCP client config:

    {
      "mcpServers": {
        "token-runway": {
          "command": "uvx",
          "args": ["token-runway"],
          "env": {
            "CLAUDE_CODE_TOKEN": "your-oauth-token"
          }
        }
      }
    }

2. GitHub Copilot

  • Automatic Discovery: Ensure the GitHub CLI (gh) is installed and authenticated:

    gh auth login

    Token Runway queries GitHub's internal Copilot quota endpoint directly through your gh session.

  • Environment Variable: Alternatively, export GH_TOKEN or GITHUB_TOKEN with Copilot permissions:

    export GH_TOKEN="ghp_..."

3. Google Gemini & Antigravity

  • Automatic Discovery: Ensure the Antigravity CLI (agy) is in your system $PATH and logged in. Token Runway polls agy -p /usage --output-format json directly.

4. Google Colab

  • Automatic Discovery: Ensure the colab command-line tool is installed and authenticated.

5. OpenRouter & OpenAI (Optional)

  • Export OPENROUTER_API_KEY or OPENAI_API_KEY:

    export OPENROUTER_API_KEY="sk-or-v1-..."
    export OPENAI_API_KEY="sk-proj-..."

    Token Runway tracks credit limits, spend, and active model access automatically.

6. Check Your Setup: doctor

Whenever you set up or add a new provider, run the doctor command to verify all integrations:

uvx token-runway doctor

It tests every local tool and remote endpoint, reporting exact connection status and active quota windows.


Quick Start

1. Run without installing (uvx)

Inspect your runway right now in your terminal:

uvx token-runway check

Output:

=== Token Runway: Live Quota Telemetry ===

Anthropic Claude
  • Current (5-Hour)           ā— CRITICAL    Used: 100%  (Remaining:   0.0%)  (Resets in 1h 18m)
  • Weekly (7-Day)             āœ” OK          Used:  76%  (Remaining:  24.0%)  (Resets in 3h 58m)

GitHub Copilot (Plan: free_limited_copilot)
  • Chat Monthly               āœ” OK          Used:   2%  (Remaining:  97.6%)  [195/200]  (Resets in 20h 1m)
  • Completions Monthly        āœ” OK          Used:   0%  (Remaining: 100.0%)  [2000/2000]  (Resets in 20h 1m)
  • Premium Monthly            - NOT ON PLAN

Google Gemini
  • Flash/Pro Weekly           āœ” OK          Used:   7%  (Remaining:  93.1%)  (Resets in 3d 13h)
  • Flash/Pro 5-Hour           āœ” OK          Used:   3%  (Remaining:  96.7%)  (Resets in 4h 37m)
  • Argon Weekly               ā— CRITICAL    Used: 100%  (Remaining:   0.0%)  (Resets in 3d 11h)

Antigravity (Claude + GPT)
  • Weekly                     āœ” OK          Used:  50%  (Remaining:  50.2%)  (Resets in 6d 16h)
  • Current (5-Hour)           āœ” OK          Used:   0%  (Remaining: 100.0%)  (Resets in 5h 0m)

Google Colab
  • Compute Units Balance      āœ” OK           [499.46]
  • Burn Rate (/hr)            āœ” OK           [0.0]
  • Active Runtimes            āœ” OK           [0.0]

2. Live Terminal HUD (watch)

Keep a live-updating quota dashboard in a split pane (top for AI quotas):

uvx token-runway watch

Displays colored ANSI progress bars ([ā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–ˆā–‘ā–‘ā–‘ā–‘] 68%) and real-time countdown tickers ticking down to the exact reset minute.

3. Zero-Dependency Web HUD (dashboard)

Launch a local dark-mode browser dashboard on http://localhost:7890:

uvx token-runway dashboard

Visual progress meters, live polling, and an interactive Assess Action Simulator to test LLM decisions in real time.

4. Embed Rules into Projects (init-rules)

Embed self-governance instructions into your project repository (CLAUDE.md, .cursorrules, .windsurfrules, AGENTS.md):

uvx token-runway init-rules

Instructs coding agents to automatically check assess_action before running expensive multi-agent sweeps or loading large files.

5. Auto-Inject into your AI IDEs

Token Runway detects your installed AI editors (Claude Desktop, Cursor, Claude Code, Antigravity, Windsurf) and injects the server configuration in one command:

uvx token-runway inject

Safety Guardrails & Strict Throttling

Enforce spending ceilings or maximum quota thresholds:

# Warn and advise downgrade when utilization exceeds 80%
uvx token-runway run --max-budget 80

# Strictly reject heavy agent actions once over 80%
uvx token-runway run --max-budget 80 --strict

Manual IDE Configuration

If you prefer configuring your editor manually, add the following to your mcpServers block:

Claude Desktop (claude_desktop_config.json) / Cursor (mcp.json)

{
  "mcpServers": {
    "token-runway": {
      "command": "uvx",
      "args": ["token-runway"]
    }
  }
}

Or using standard python:

{
  "mcpServers": {
    "token-runway": {
      "command": "python",
      "args": ["-m", "token_runway"]
    }
  }
}

What the Agent Sees

Token Runway registers tools, resources, and prompts with the host IDE:

1. assess_action (Tool)

Agents call this before embarking on expensive actions:

{
  "name": "assess_action",
  "arguments": {
    "action_type": "subagent_fanout",
    "intensity": "high"
  }
}

Sample Response:

{
  "verdict": "pause_or_downgrade",
  "max_utilization_pct": 100,
  "bottleneck": {
    "provider": "Anthropic Claude",
    "window": "Current (5-Hour)",
    "resets_in_minutes": 78
  },
  "analysis": "Quota is critically constrained (100% used on Anthropic Claude Current (5-Hour)).",
  "preservation_strategies": [
    "Prohibit parallel subagent fan-outs; execute one step at a time.",
    "Read narrow line ranges (under 100 lines) instead of loading full files into context.",
    "Route subagent prompts to lightweight models (Flash/Haiku) if model selection is supported."
  ]
}

2. check_runway (Tool)

Returns a structured JSON snapshot of all active provider limits, reset times, and plan types.

3. runway://status (Resource)

Real-time JSON context stream that clients can pin to the context window.

4. runway_governance (Prompt)

System prompt guidelines teaching the agent how to budget tokens and adapt when limits are tight.


Diagnostic Doctor

Run doctor to verify which local CLIs and authentication tokens are ready:

uvx token-runway doctor
=== Token Runway: Doctor ===

  āœ” Claude Code: Credentials found
  āœ” Antigravity CLI (`agy`): Found in PATH
  āœ” GitHub CLI (`gh`): Found in PATH
  āœ” Google Colab CLI (`colab`): Found in PATH

Checking live endpoints...
  āœ” Anthropic Claude: Connected (2 quota windows active)
  āœ” GitHub Copilot: Connected (3 quota windows active)
  āœ” Google Gemini: Connected (3 quota windows active)
  āœ” Antigravity (Claude + GPT): Connected (2 quota windows active)
  āœ” Google Colab: Connected (3 quota windows active)

Doctor check completed.

Design Philosophy

  • Zero Runtime Dependencies: Written entirely in pure Python standard library (json, urllib, subprocess, dataclasses). Fast startup, no wheel compilation, no broken dependency trees.

  • Fail-Safe & Non-Blocking: If a CLI is missing or a service times out, Token Runway reports available: false with a clear explanation without crashing the MCP connection.

  • Privacy First: Runs entirely on your local machine over standard input/output (stdio). No usage data or tokens are sent to any third-party telemetry servers.


Contributing & Development

git clone https://github.com/Cpleasance/token-runway.git
cd token-runway
pip install -e ".[dev]"

# Run tests
pytest -v

# Run linter
ruff check .

License

MIT License — Copyright (c) 2026 Cory Pleasance.

Available Tools

2 tools
assess_actionB

Meta-cognitive evaluation of whether a proposed action (e.g. running multiple parallel subagents, reading massive files, or continuous test loops) is justified given current remaining provider quotas and reset timers.

NameRequiredDescriptionDefault
strictNoIf true, strictly reject actions when over budget.
providerNoTarget provider whose limits you want to evaluate against ('claude', 'gemini', etc.).
intensityNoEstimated token burn intensity of the action.medium
max_budgetNoMaximum allowed utilization percentage before pausing (0-100).
action_typeNoType of action planned ('subagent_fanout', 'large_file_dump', 'deep_research', 'targeted_edit', 'continuous_loop').general

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full disclosure burden. It conveys that the tool reads current quota and reset-timer state, but never says whether it merely advises or actually blocks actions, whether it is read-only, or what verdict/response shape it returns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence with no wasted clauses, front-loading the core function before the parenthetical examples. The only weakness is the jargon 'meta-cognitive evaluation,' which adds no operational meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With five parameters, no annotations, and no output schema, the description should explain what the evaluation returns (allow/reject recommendation, budget figures) and how strict and max_budget interact. Neither is covered, leaving a significant gap for a decision-support tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented in the schema; the description adds only illustrative action examples that overlap with the action_type enum. Baseline 3 is appropriate since the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific function: evaluating whether a proposed action is justified against remaining provider quotas and reset timers, with concrete example actions. It is clear what the tool does, but it never acknowledges or differentiates itself from the sibling check_runway, leaving the boundary between 'assess an action' and 'check runway' implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied through examples (parallel subagents, massive file reads, test loops), which gesture at when to call it. There is no explicit when-to-use, when-not-to-use, or mention of the alternative check_runway tool, so the agent must infer the routing decision.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_runwayA

Inspect current AI provider rate-limit windows, quota utilization percentages, remaining capacity, and reset countdowns across Claude, Gemini, Antigravity, GitHub Copilot, Colab, OpenRouter, and OpenAI. Note: This reflects provider quota windows and rate limits, not session token counts.

NameRequiredDescriptionDefault
refreshNoBypass cache and force an immediate re-fetch from provider CLIs/APIs.
providerNoOptional provider filter ('claude', 'gemini', 'antigravity', 'copilot', 'colab', 'openrouter', 'openai').

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. 'Inspect' implies a read-only operation and the note clarifying that this reflects provider quota windows rather than session token counts is genuinely valuable disambiguation, but auth requirements, caching behavior, and the shape of the response are left unstated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core capability and followed by a scope exclusion. The provider list is long but purposeful; there is essentially no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description does the work of describing what comes back — utilization percentages, remaining capacity, reset countdowns — and explicitly rules out session token counts. Only auth/caching details are missing, which is minor for a two-optional-parameter read tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented, including the refresh bypass and the provider filter values. The description's provider enumeration mirrors the schema's provider list rather than adding syntax or format detail, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Inspect') and a concrete resource set — rate-limit windows, quota utilization, remaining capacity, reset countdowns — and enumerates the seven providers covered. It is immediately clear what the tool does, though it never distinguishes itself from the sibling assess_action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the resource it inspects (checking provider quota windows), and the closing note usefully excludes session token counts. However, there is no explicit 'use when' statement and no reference to when assess_action would be the better choice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.2.2
    • First observedassess_action
    • First observedcheck_runway

TDQS

A3.5/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct roles: check_runway retrieves quota/rate-limit data, while assess_action performs a judgment about whether a proposed action is justified. An agent should not confuse data inspection with meta-cognitive assessment.

Naming Consistency5/5

Both names follow a consistent snake_case verb_noun pattern: check_runway and assess_action. The verbs differ but the convention is predictable and readable.

Tool Count3/5

Two tools is thin for a server, even a narrowly scoped one. The pair covers inspection and assessment, but additional operations such as listing providers or comparing options could reasonably earn a place.

Completeness4/5

The surface covers the core lifecycle of checking current runway and assessing proposed actions against it. Minor gaps exist around historical trends, threshold configuration, or provider comparison, but agents can work around them.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables agents to track real-time token spend and cost velocity, automatically throttle or freeze execution when budgets are exceeded, and enforce sandbox and safety guardrails.
    7
    MIT
  • F
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents and MCP-compatible clients to enforce multi-provider token-bucket and sliding-window rate limits, preventing TPM/RPM throttling across LLM APIs with predictive token consumption budgeting.
    7
    -