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

Ponytail tracks the active intensity level through a coordinated three-part mechanism: a CLI command defined in commands/ponytail.toml that persists user preferences, a resolveMode function in ponytail-mcp/instructions.js that determines the runtime intensity, and an activation hook in 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, 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 (line 323), the command follows this pattern:

# 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 (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.

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 (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.

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:

ponytail

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

Changing Intensity Modes

To switch to a different enforcement level:

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:

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 provides the interface for setting and querying intensity, persisting values between sessions.
• Runtime Logic: ponytail-mcp/instructions.js contains the resolveMode function (line 13) that determines the effective intensity with fallback handling.
• Rule Filtering: 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 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 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. 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.

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