In Agent development, the context window is a hard constraint. Instruction files, Skills, MCP tool definitions, and Memory all consume tokens. In particular, a Skill’s catalog (present in every request) and body (loaded on demand) represent two different cost types. In addition, MCP tool definitions impose a “permanent tax.”

Introduction

Before an Agent starts running, how much does its context cost? This is a question that must be confirmed during the model inference phase. As a DSH plugin, ctx-budget audits context cost before an Agent runs. It identifies the text an Agent will load—instruction files, Skills, MCP tool definitions, and Memory—measures each item, and distinguishes what is paid for in every request (catalogs) from what is paid for only when loaded (bodies). Finally, it provides an exit code that can be enforced in CI.

What It Is

ctx-budget is a DSH plugin maintained by liyixuan201211 and released under the MIT License. It primarily addresses three problems:

  1. Distinguishing two cost types: Instruction files and Skill catalogs are present in every request, while Skill bodies exist only when loaded. Most tools cannot distinguish between the two, making it hard to locate budget overruns.
  2. The permanent tax of MCP tools: Tool definitions add tokens to every model request, whether or not the model invokes a tool.
  3. Description truncation: Overly long descriptions may be truncated, causing useful information to be lost.

The plugin measures by reading files and does not involve processes, sockets, or write operations.

Core Features

  1. Audit by source: Measures the consumption of instruction files, Skills, MCP tool definitions, and Memory item by item.
  2. Pre-run measurement: Produces a context cost estimate before the Agent runs.
  3. Layered statistics: Separates always-on (catalog) costs from on-demand (body) costs.
  4. Duplicate detection: Detects duplicate text blocks and labels them by consumption tier.
  5. CI exit codes: Provides an exit code that allows budgets to be enforced in CI pipelines.
  6. CJK-aware token estimation: Uses ratios of 4 characters per token (ASCII) and 1.5 characters per token (CJK) for estimation, avoiding underestimating Chinese token consumption by about 2.44×.
  7. Safe reads: Reads files only; does not execute processes, open sockets, or write files.

Installation and Activation

Install the plugin using the DSH CLI:

dsh plugin --profile web add github:liyixuan201211/ctx-budget

After installation, the skill is loaded into the current DSH environment.

Typical Usage

After installing the plugin, it can be run directly from the command line:

ctx-budget

Set a maximum budget threshold:

ctx-budget --max 40000

Specify a particular MCP tool file to audit:

ctx-budget --mcp-tools tools.

Audit a specified project root directory:

ctx-budget --root ./chinese-project --

View help information:

npx --yes github:liyixuan201211/ctx-budget --help

Use Cases and Caveats

Use cases: Projects that need to enforce context budgets in CI; developers who want to optimize Skill design to reduce token consumption; projects handling multiple languages, including Chinese.

Caveats:

  • Chinese estimation: Chinese character counts are more sensitive than English. Without CJK-aware estimation, the 4 characters per token rule would underestimate Chinese token consumption by approximately 2.44×. The plugin uses different ratios by default for ASCII, CJK, and other non-ASCII text (defaults: 4.0, 1.5, and 2.5).
  • Exit code meaning: Exit code 5 means “could not determine.” This usually occurs when an MCP server declares tools but does not export their definitions. The report then provides a lower bound and does not guarantee that the budget will pass.
  • Safety mechanism: The plugin only reads files; it performs no process calls, network communication, or file writes, making it safe to run in CI environments.

Summary

ctx-budget provides a way to quantify an Agent’s context cost before it runs. By distinguishing always-on and on-demand costs and detecting duplicate text blocks, developers can control token consumption more precisely. Together with CI exit codes, it can bring context management into the development workflow.