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

> Easily switch Ponytail intensity levels lite full or ultra at runtime using CLI flags environment variables or the API. Learn 3 methods without restarting.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: how-to-guide
- Published: 2026-09-06

---

**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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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.

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

ponytail -i ultra           # switch to the ultra intensity

```

The flag is defined in [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) reads `PONYTAIL_INTENSITY` and makes it available to `resolveMode`. Changing the variable updates the intensity instantly—no restart required.

```js
// 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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).

## Method 3: Use the Programmatic Runtime API

For dynamic switches inside a running application, [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) exports `setMode(mode)`. This calls `resolveMode` under the hood and refreshes the rule set.

```javascript
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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) | Defines `MODES` array and `resolveMode()` logic |
| [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) | Reads `PONYTAIL_INTENSITY` env var and default mode |
| [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) | Exports `setMode(mode)` for programmatic control |
| [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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.