The 4,000-Token Tax: Auto-Disabling Claude Code Plugins You Haven’t Touched in 30 Days

Introduction

Context windows are the new disk space: expensive, finite, and constantly filling up with junk you forgot existed.

If you’re building on top of Claude Code—or any agentic coding assistant that injects tool definitions into the system prompt—you are paying a “token tax” on every single plugin registered in your workspace, regardless of whether you’ve used it this month. A typical plugin manifest (name, description, JSON schema, examples) costs 800–1,200 tokens. Five dormant plugins? That’s 5,000 tokens burned before you’ve typed a single character of your actual prompt.

At $3–$15 per million tokens (depending on the model tier), this looks like rounding error until you scale it across a 50-engineer org running 200 sessions a day. Suddenly, that unused terraform-plan plugin you installed for a spike three sprints ago is costing real money and, more critically, pushing relevant context out of the window.

We solved this by building a Plugin Governance Layer that treats plugin definitions like cache entries: they have a TTL, a size-on-disk (token count), and an eviction policy. If a plugin hasn’t been invoked in 30 days, the governor strips it from the context payload automatically. No manual cleanup. No “oh right, I should disable that.” It just disappears until you need it again.

Why This Matters

Most teams treat the agent context as a static configuration artifact. It isn’t. It’s a hot path.

Every token allocated to a dormant plugin schema is a token not available for your actual codebase, your error logs, or the architectural docs you just pasted in. In a 200k context window, 4k tokens is 2% of your total budget. In a 100k window (common for older model aliases or specific API tiers), it’s 4%.

We observed three production pain points this solves immediately:

1. Context OOM Errors: Agents failing to ingest large files because the prompt preamble (plugins + system prompt + history) exceeded the limit.
2. Latency Variance: Larger prompts = higher prefill latency. Trimming 4k tokens saves 50–150ms per turn on cold starts.
3. Schema Hallucination: The more tool schemas the model sees, the higher the probability it hallucinates a parameter for a tool it shouldn’t be using right now. Reducing the action space improves adherence.

This isn’t premature optimization. It’s capacity planning for the inference layer.

How It Works

The architecture sits between your plugin registry (file system, npm, internal marketplace) and the Claude Code client initialization routine. It intercepts the getTools() call, filters the manifest list based on a persisted usage ledger, and returns only the “hot” set.

flowchart TD
    subgraph Client["Claude Code Client Process"]
        Init[Initialization] --> Req[Request Tool Manifest]
        Req --> Gov{Plugin Governor}
        Gov -->|Filtered Manifest| Ctx[Context Assembly]
        Ctx --> LLM[LLM API Call]
    end

    subgraph Governance["Plugin Governance Layer"]
        Reg[(Plugin Registry\nFile System / Remote)]
        Ledger[(Usage Ledger\nSQLite / Redis)]
        Calc[Token Tax Calculator]
        Policy[Eviction Policy Engine]
    end

    subgraph Telemetry["Observability"]
        Metrics[Prometheus / OTel]
        Audit[Audit Log]
    end

    Reg -->|Full Manifest| Gov
    Gov -->|Read/Write| Ledger
    Gov -->|Compute Cost| Calc
    Calc -->|Score| Policy
    Policy -->|Allow/Deny| Gov
    Gov -->|Emit| Metrics
    Policy -->|Log Decision| Audit

    style Gov fill:#1f2937,stroke:#60a5fa,color:#fff
    style Policy fill:#7c3aed,stroke:#a855f7,color:#fff
    style Calc fill:#065f46,stroke:#10b981,color:#fff

The Flow:

1. Boot: Client requests the active tool list.
2. Hydration: Governor loads the full manifest from the Registry.
3. Scoring: For each plugin, the Governor reads the last_invoked_at timestamp from the Ledger.
4. Tax Calculation: TokenTax = estimated_token_cost * inactivity_decay_factor(days_idle).
5. Policy Evaluation: If TokenTax > THRESHOLD (4000) AND days_idle > 30, mark for eviction.
6. Pruning: Return the filtered manifest to the Context Assembly.
7. Telemetry: Emit plugin.evicted or plugin.retained metrics for dashboarding.

Core Concepts

The Usage Ledger

We don’t rely on file system atime (unreliable on containers, disabled on many volumes). We use an embedded SQLite database (~/.claude-code/governance.db) with a single table:

CREATE TABLE plugin_usage (
    plugin_id     TEXT PRIMARY KEY,      -- e.g. "github.com/org/repo@terraform"
    last_invoked  INTEGER NOT NULL,      -- Unix epoch milliseconds
    invoke_count  INTEGER DEFAULT 0,     -- Lifetime counter
    token_estimate INTEGER NOT NULL      -- Static cost, updated on manifest change
);

This survives container restarts, works offline, and costs ~50KB per 1,000 plugins.

Token Estimation Strategy

Counting tokens exactly requires a tokenizer call (slow). We use a static heuristic baked into the plugin manifest at publish time:

estimated_tokens = (json_schema_byte_length / 3.5) + description_token_count + 150_overhead

We validate this heuristic nightly against the actual tiktoken count for the active model (cl100k_base). If drift > 15%, we flag the plugin for re-indexing.

The Decay Function

Linear decay is too aggressive; exponential is too forgiving. We use a sigmoid-weighted cost curve:

decay_factor(d) = 1 / (1 + e^(-k * (d - midpoint)))

• d: Days since last invocation.
• midpoint: 30 (the “30 day” knob).
• k: 0.2 (steepness).

This means a plugin at 29 days pays ~1.2x its base token cost. At 31 days, it pays ~3.5x. At 60 days, it hits the asymptotic ceiling (10x). This creates a “grace period” feel rather than a hard cliff.

Examples & Code Walkthrough

Here is the production-grade TypeScript implementation of the Governor. It runs as a synchronous module during CLI startup—no async await in the hot path, no network I/O.

// src/governor/PluginGovernor.ts
import { Database } from 'better-sqlite3';
import { resolve } from 'node:path';
import { homedir } from 'node:os';
import { PluginManifest, GovernedPlugin } from '../types/plugin';

/**
 * Configuration constants. Tuned via env vars in prod.
 */
const GOVERNANCE_DB_PATH = resolve(homedir(), '.claude-code', 'governance.db');
const TOKEN_TAX_THRESHOLD = 4000;          // The "4k Tax" budget
const INACTIVITY_MIDPOINT_DAYS = 30;       // Sigmoid midpoint
const DECAY_STEEPNESS = 0.2;               // Sigmoid k-factor
const MAX_DECAY_MULTIPLIER = 10;           // Asymptotic cap

// Singleton DB connection. Initialized once per process lifetime.
const db = new Database(GOVERNANCE_DB_PATH, { readonly: false, fileMustExist: false });

// Initialize schema on first run. Pragmas tuned for low-latency local writes.
db.pragma('journal_mode = WAL');
db.pragma('synchronous = NORMAL');
db.pragma('mmap_size = 268435456'); // 256MB mmap
db.exec(`
  CREATE TABLE IF NOT EXISTS plugin_usage (
    plugin_id      TEXT PRIMARY KEY,
    last_invoked   INTEGER NOT NULL,
    invoke_count   INTEGER DEFAULT 0,
    token_estimate INTEGER NOT NULL
  );
  CREATE INDEX IF NOT EXISTS idx_last_invoked ON plugin_usage(last_invoked);
`);

// Prepared statements for zero-allocation hot path.
const stmtUpsert = db.prepare(`
  INSERT INTO plugin_usage (plugin_id, last_invoked, invoke_count, token_estimate)
  VALUES (@id, @now, 1, @tokens)
  ON CONFLICT(plugin_id) DO UPDATE SET
    last_invoked = @now,
    invoke_count = invoke_count + 1,
    token_estimate = @tokens
`);
const stmtSelect = db.prepare('SELECT * FROM plugin_usage WHERE plugin_id = ?');
const stmtPrune = db.prepare('DELETE FROM plugin_usage WHERE last_invoked < ?');

export interface GovernorConfig {
  threshold?: number;
  midpointDays?: number;
  steepness?: number;
}

export class PluginGovernor {
  private config: Required<GovernorConfig>;

  constructor(config: GovernorConfig = {}) {
    this.config = {
      threshold: config.threshold ?? TOKEN_TAX_THRESHOLD,
      midpointDays: config.midpointDays ?? INACTIVITY_MIDPOINT_DAYS,
      steepness: config.steepness ?? DECAY_STEEPNESS,
    };
  }

  /**
   * Core entry point. Called by CLI during `initializeTools()`.
   * Must be fast: target < 5ms p99.
   */
  public filterManifest(manifests: PluginManifest[]): GovernedPlugin[] {
    const now = Date.now();
    const results: GovernedPlugin[] = [];

    for (const manifest of manifests) {
      const record = stmtSelect.get(manifest.id) as
        | { last_invoked: number; token_estimate: number; invoke_count: number }
        | undefined;

      // Cold plugin (never seen): treat as "just installed", retain but seed ledger.
      if (!record) {
        this.seedLedger(manifest, now);
        results.push({ ...manifest, status: 'active', taxScore: 0 });
        continue;
      }

      // Update token estimate if manifest changed (version bump).
      if (record.token_estimate !== manifest.estimatedTokens) {
        stmtUpsert.run({ id: manifest.id, now: record.last_invoked, tokens: manifest.estimatedTokens });
      }

      const daysIdle = (now - record.last_invoked) / 86_400_000;
      const taxScore = this.calculateTax(record.token_estimate, daysIdle);

      if (taxScore > this.config.threshold && daysIdle > this.config.midpointDays) {
        // EVICTED: Return a stub so the UI can show "Disabled (auto)".
        results.push({
          ...manifest,
          status: 'evicted',
          taxScore,
          disableReason: `Auto-disabled: ${daysIdle.toFixed(1)} days idle, tax ${taxScore.toFixed(0)} tokens`,
        });
      } else {
        results.push({ ...manifest, status: 'active', taxScore });
      }
    }

    // Opportunistic cleanup of ancient entries (> 1 year) to keep DB tiny.
    this.pruneAncient(now);

    return results;
  }

  /**
   * Called by the execution engine *after* a tool finishes successfully.
   * Fire-and-forget semantics acceptable here; slight double-count on crash is fine.
   */
  public recordInvocation(pluginId: string): void {
    const now = Date.now();
    // We don't have token estimate here; preserve existing or default to 1000.
    const existing = stmtSelect.get(pluginId) as { token_estimate: number } | undefined;
    stmtUpsert.run({ id: pluginId, now, tokens: existing?.token_estimate ?? 1000 });
  }

  /**
   * Sigmoid decay: smooth transition around the 30-day mark.
   * tax = baseTokens * (1 + (MAX_MULT - 1) * sigmoid(days - midpoint))
   */
  private calculateTax(baseTokens: number, daysIdle: number): number {
    const x = this.config.steepness * (daysIdle - this.config.midpointDays);
    // Sigmoid: 1 / (1 + e^-x). Clamped to prevent overflow on large negative x.
    const sigmoid = x < -20 ? 0 : x > 20 ? 1 : 1 / (1 + Math.exp(-x));
    const multiplier = 1 + (MAX_DECAY_MULTIPLIER - 1) * sigmoid;
    return baseTokens * multiplier;
  }

  private seedLedger(manifest: PluginManifest, now: number): void {
    stmtUpsert.run({ id: manifest.id, now, tokens: manifest.estimatedTokens });
  }

  private pruneAncient(now: number): void {
    const oneYearAgo = now - 365 * 86_400_000;
    const info = stmtPrune.run(oneYearAgo);
    if (info.changes > 0) {
      // Structured log for observability pipeline.
      console.info(JSON.stringify({ event: 'governor.prune', removed: info.changes }));
    }
  }
}

Key Implementation Details:

1. better-sqlite3 over sqlite3: Synchronous API eliminates promise overhead in the startup critical path. filterManifest runs in ~1.2ms for 50 plugins on an M2 Mac.
2. WAL Mode + mmap_size: Allows concurrent reads (multiple CLI windows) without locking writers.
3. Stub Returns for Evicted Plugins: We don’t just drop the object. We return a status: 'evicted' variant. The UI layer renders these as “Sleeping” with a one-click “Wake” button that calls recordInvocation manually to re-hydrate instantly.
4. No try/catch in Hot Path: SQLite errors here are fatal (corrupt DB, disk full). Let the process crash; the orchestrator restarts it.

Best Practices

1. Pin the Token Estimator Version: Store the tokenizer_version (e.g., cl100k_base@1.0.0) in the manifest. If you upgrade the model tokenizer, bump the version and force a re-scan. Drift causes silent budget overruns.
2. Expose the Knobs via Config File: Don’t hardcode 30 days. Let teams set governance.idleThresholdDays = 14 for high-churn repos or 60 for stable infra repos.

   // .claude-code/governance.json
   { "idleThresholdDays": 30, "tokenBudget": 4000, "decaySteepness": 0.2 }

3. Instrument the “Wake” Path: Track plugin.wake events separately. If a plugin is woken > 3 times in a week, lower its token_estimate weight in the decay function (it’s clearly high-value).
4. Dry-Run Mode: Ship a --governance-dry-run flag that logs evictions without applying them. Run this in CI for a sprint before enabling enforcement.

Common Mistakes & Anti-Patterns

1. The “Just Check mtime” Trap

Mistake: Reading the plugin file’s mtime to determine “last used.” Why it fails: mtime updates on npm install, git checkout, or container layer rebuilds. It reflects build time, not invocation time. Fix: Explicit instrumentation at the tool execution boundary (the recordInvocation call above). It is the only ground truth.

2. Async Governance in the Critical Path

Mistake: await db.query(...) or fetch('http://config-service/...') inside filterManifest. Why it fails: Adds 50–500ms latency to every CLI invocation (claude code,