How to Switch Ponytail Intensity Levels at Runtime: 3 Methods Explained

Ponytail's intensity levels (lite, full, ultra) can be changed at runtime via CLI flag, environment variable, or programmatic API without restarting the process.

Switching Ponytail intensity levels at runtime lets you dynamically trade off rule coverage against performance. The framework defines three supported intensities and resolves the effective intensity through the resolveMode helper in ponytail-mcp/instructions.js. This article covers all three methods to change intensity while your application stays running.

What Are Ponytail Intensity Levels?

Ponytail enforces three built-in intensity modes:

• lite — minimal rule coverage, fastest execution
• full — balanced rule coverage (default)
• ultra — maximum rule coverage, most thorough analysis

These modes are defined in ponytail-mcp/instructions.js. The resolveMode(requested) function normalizes input, falls back to the configured default via getDefaultMode(), and ultimately defaults to full if no match exists.

Method 1: Pass an Explicit Intensity on the Command Line

The CLI flag --intensity (short form -i) parses user input and feeds it into the MCP request. This takes effect immediately for the next command invocation.

ponytail --intensity=lite   # switch to the lite intensity

ponytail -i ultra           # switch to the ultra intensity

The flag is defined in commands/ponytail.toml as part of the built-in command module.

Method 2: Set the PONYTAIL_INTENSITY Environment Variable

The configuration hook hooks/ponytail-config.js reads PONYTAIL_INTENSITY and makes it available to resolveMode. Changing the variable updates the intensity instantly—no restart required.

// Change intensity via environment variable (Node process)
process.env.PONYTAIL_INTENSITY = 'ultra';

// Optional: trigger reload via signal if your app has a watcher
process.kill(process.pid, 'SIGHUP');

If PONYTAIL_INTENSITY is unset, the system falls back to the default mode configured in hooks/ponytail-config.js.

Method 3: Use the Programmatic Runtime API

For dynamic switches inside a running application, hooks/ponytail-runtime.js exports setMode(mode). This calls resolveMode under the hood and refreshes the rule set.

import { setMode } from './hooks/ponytail-runtime.js';

await setMode('lite');   // switch to lite while the app is running
await setMode('full');   // later switch back to full

This is the most flexible approach for applications that need to adjust intensity based on real-time conditions or user preferences.

How Intensity Resolution Works

All three methods ultimately invoke resolveMode(requested) in ponytail-mcp/instructions.js. The resolution chain works as follows:

1. Normalize the requested intensity string
2. Fall back to getDefaultMode() if the request is invalid or empty
3. Default to full if no configuration exists

This ensures predictable behavior regardless of which switching method you use.

Key Source Files for Runtime Intensity Control

File	Purpose
ponytail-mcp/instructions.js	Defines MODES array and resolveMode() logic
hooks/ponytail-config.js	Reads PONYTAIL_INTENSITY env var and default mode
hooks/ponytail-runtime.js	Exports setMode(mode) for programmatic control
commands/ponytail.toml	CLI definition with --intensity / -i option

Summary

• CLI flag (--intensity or -i) — best for one-off command invocations
• Environment variable (PONYTAIL_INTENSITY) — best for containerized or scripted deployments
• Programmatic API (setMode()) — best for dynamic, runtime-driven applications

All approaches leverage resolveMode() in ponytail-mcp/instructions.js and require no process restart.

Frequently Asked Questions

What happens if I pass an invalid intensity value?

resolveMode() normalizes the input and falls back to getDefaultMode(). If no default is configured, it defaults to full. No error is thrown—Ponytail prioritizes stable operation over strict validation.

Can I switch intensity multiple times in a single process?

Yes. The setMode() API and environment variable changes both take effect immediately. Each call or change triggers resolveMode() and refreshes the active rule set without restarting.

Does changing intensity affect in-progress analyses?

The new intensity applies to subsequent operations. In-progress analyses typically complete with the intensity level they started under, though this depends on how your application implements the runtime hooks.

What's the performance difference between lite, full, and ultra?

Lite mode skips computationally expensive rules for maximum speed. Full mode provides balanced coverage. Ultra mode enables all available rules for thorough analysis at the cost of execution time. The exact performance characteristics depend on your rule set and codebase size.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}