# How Ponytail Tracks the Active Intensity Level: CLI Persistence, Runtime Logic, and Rule Filtering

> Discover how Ponytail tracks active intensity using CLI persistence, runtime logic, and rule filtering. Understand the core mechanisms behind this powerful tool.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: internals
- Published: 2026-09-08

---

**Ponytail tracks the active intensity level through a coordinated three-part mechanism: a CLI command defined in [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) that persists user preferences, a `resolveMode` function in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) that determines the runtime intensity, and an activation hook in [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) that filters the ruleset to match the current level.**

The DietrichGebert/ponytail repository implements a tiered intensity system that controls how aggressively coding rules are enforced during agent execution. Whether running in *lite*, *full* (default), *ultra*, or *off* mode, understanding how Ponytail tracks the active intensity level ensures developers can reliably customize rule enforcement across CLI interactions and runtime sessions.

## Understanding Ponytail Intensity Levels

Ponytail supports four distinct intensity tiers that determine ruleset strictness:

- **lite** – Applies minimal rules for quick suggestions
- **full** – The default mode with balanced rule enforcement
- **ultra** – Maximum strictness with aggressive rule application
- **off** – Disables rule enforcement entirely

These modes are referenced throughout the codebase, from CLI argument parsing to runtime rule filtering.

## The Three-Component Tracking System

### CLI Command and Persistence

The entry point for intensity management resides in **[`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml)**, which defines the command interface for querying and setting the active level. When invoked without arguments, the CLI reports the currently persisted intensity. When passed an argument like `ultra`, it updates the stored mode for subsequent sessions.

According to the usage documentation in **[`README.md`](https://github.com/DietrichGebert/ponytail/blob/main/README.md)** (line 323), the command follows this pattern:

```bash

# Query current intensity

$ ponytail
Current Ponytail intensity: full

# Update to ultra mode

$ ponytail ultra
Ponytail intensity set to ultra

```

This CLI layer handles persistence, ensuring the chosen intensity survives across separate agent invocations.

### Runtime Resolution Logic

Once a session begins, **[`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js)** (line 13) provides the single source of truth for determining the effective intensity. The **`resolveMode`** helper function maps user requests to runtime values, implementing fallback logic for edge cases.

When the user passes "off", an empty string, or an unrecognized value, `resolveMode` falls back to the persisted intensity level. This ensures the system never runs with an undefined state.

```javascript
import { resolveMode } from 'ponytail-mcp/instructions.js';

// Resolve effective intensity for current run
const intensity = resolveMode(process.env.PONYTAIL_MODE);
console.log(`Running with intensity: ${intensity}`);
// → Running with intensity: ultra

```

### Rule-Set Filtering During Activation

The final tracking component operates at activation time. In **[`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js)** (line 41), the framework emits the ruleset filtered to the active intensity level. This hook consults the intensity obtained from `resolveMode` and strips out any rule rows belonging to other tiers before passing the subset to the execution engine.

```javascript
import { filterRulesByIntensity } from 'hooks/ponytail-activate.js';

const fullRules = loadRules();               // loads all rule rows
const activeRules = filterRulesByIntensity(fullRules, intensity);
// activeRules contains only rows matching current intensity

```

This filtering ensures that only rules appropriate for the *lite*, *full*, or *ultra* designation are applied during the session.

## Working with Intensity in Practice

### Querying the Current Level

To verify the active intensity without modifying it:

```bash
ponytail

```

The command reads the persisted value and outputs the current setting.

### Changing Intensity Modes

To switch to a different enforcement level:

```bash
ponytail ultra

```

This updates the stored configuration and confirms the change.

### Programmatic Access in Plugins

For developers extending Ponytail, accessing the intensity programmatically ensures consistent behavior:

```javascript
import { resolveMode } from 'ponytail-mcp/instructions.js';

const currentIntensity = resolveMode(process.env.PONYTAIL_MODE);

if (currentIntensity === 'ultra') {
  // Apply additional strict checks
}

```

## Summary

- **CLI Layer**: [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) provides the interface for setting and querying intensity, persisting values between sessions.
- **Runtime Logic**: [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) contains the `resolveMode` function (line 13) that determines the effective intensity with fallback handling.
- **Rule Filtering**: [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) (line 41) filters the complete ruleset to include only rules matching the active intensity level.
- **Supported Modes**: lite, full (default), ultra, and off.

## Frequently Asked Questions

### What intensity levels does Ponytail support?

Ponytail supports four levels: **lite** for minimal enforcement, **full** as the balanced default, **ultra** for maximum strictness, and **off** to disable rules entirely. These are defined in the CLI configuration and resolved at runtime via the `resolveMode` function.

### How does Ponytail handle invalid intensity inputs?

When `resolveMode` in [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) receives "off", an empty string, or an unrecognized value, it automatically falls back to the previously persisted intensity level. This prevents the system from entering an undefined state.

### Can plugins access the current intensity level programmatically?

Yes. Plugins can import `resolveMode` from [`ponytail-mcp/instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mcp/instructions.js) and pass the environment variable or requested mode to determine the current intensity. This ensures custom logic respects the user's chosen enforcement level.

### Where does Ponytail store the active intensity between commands?

The intensity is persisted through the CLI command mechanism defined in [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml). When you run `ponytail ultra`, the framework stores this preference, making it available to the `resolveMode` function in subsequent sessions via the standard configuration persistence layer.