How to Use the `/ponytail` Command to Switch Intensity Modes

Use /ponytail <mode> to change Ponytail's code‑generation intensity, where <mode> is lite, full, ultra, off, or default <mode> to persist your choice for future sessions.

The /ponytail command is the primary interface for controlling how aggressively Ponytail guides your LLM-assisted coding. Whether you want minimal hints or exhaustive step‑by‑step instructions, this command lets you dial in the right level of assistance. This guide walks through the exact syntax, available intensity levels, and how the ponytail-mode-tracker.js hook processes your commands.

Understanding Intensity Modes

Ponytail defines three active intensity levels plus an off state:

• lite — Lightweight guidance with high‑level suggestions
• full — Standard, detailed code‑generation instructions
• ultra — Maximum verbosity with exhaustive explanations
• off — Disables Ponytail for the current session only

Intensity modes control the depth of instructions injected into your LLM prompts. According to the DietrichGebert/ponytail source, the mode tracker in hooks/ponytail-mode-tracker.js validates these options at lines 31‑55 before activating any changes.

Basic Syntax for Switching Modes

Session-Only Mode Changes

To change intensity for the current conversation without affecting future sessions:

// Switch to lite intensity
{ "prompt": "/ponytail lite" }

// Switch to full intensity
{ "prompt": "/ponytail full" }

// Switch to ultra intensity
{ "prompt": "/ponytail ultra" }

The finish() function in hooks/ponytail-mode-tracker.js:18‑23 parses your prompt, normalizes it to lowercase, and extracts the command at lines 23‑27. If a valid runtime mode is detected, setMode(mode) (lines 64‑80) stores the flag file and emits confirmation.

Persisting a Default Mode

To save your preferred intensity for all future sessions:

// Persist ultra as the default
{ "prompt": "/ponytail default ultra" }

The writeDefaultMode(dmode) function at lines 38‑44 persists your choice to ~/.config/ponytail/config.json (respecting XDG directories). On the next session, getDefaultMode() in hooks/ponytail-config.js:76‑85 reads this value automatically.

Checking and Disabling Intensity

Query Current Mode

Running /ponytail without arguments reports the active intensity without making changes:

{ "prompt": "/ponytail" }

The hook responds with the current mode status, useful for verifying your configuration.

Disable Ponytemporarily

To turn off Ponytail guidance for the remainder of the session:

{ "prompt": "/ponytail off" }

Unlike mode changes, off clears the flag file rather than writing a new one (lines 64‑80). This state does not persist—your saved default will reactivate on the next session.

How the Mode Tracker Processes Commands

The ponytail-mode-tracker.js hook operates in six distinct stages when handling /ponytail commands:

1. Parse input — finish() reads data.prompt and normalizes case (lines 18‑23)
2. Detect command — Identifies /ponytail or @/ponytail prefix (lines 23‑27)
3. Route arguments — Dispatches to default, mode setter, or report handler (lines 31‑55)
4. Activate mode — setMode() writes flag file or clears for off (lines 64‑80)
5. Persist if requested — writeDefaultMode() updates config.json (lines 38‑44)
6. Emit feedback — writeHookOutput() returns JSON with confirmation (lines 58‑63)

The response format follows this structure:

{
  "type": "UserPromptSubmit",
  "data": "lite",
  "message": "PONYTAIL MODE CHANGED — level: lite"
}

Command Reference

Command	Effect	Persistence
/ponytail lite	Lite intensity guidance	Session only
/ponytail full	Full intensity guidance	Session only
/ponytail ultra	Ultra intensity guidance	Session only
/ponytail off	Disable Ponytail	Session only
/ponytail default <mode>	Set <mode> as new default	Permanent
/ponytail	Report current mode	None

Related Files in the Repository

File	Purpose
hooks/ponytail-mode-tracker.js	Core command parser and mode state manager
hooks/ponytail-config.js	Config file I/O and environment resolution
hooks/ponytail-instructions.js	Generates human‑readable instruction text post‑switch
pi-extension/index.js	Registers /ponytail for Pi extension hosts

Summary

• /ponytail accepts lite, full, ultra, off, or default <mode> as arguments
• Runtime modes apply immediately but expire with the session
• default <mode> writes to ~/.config/ponytail/config.json via writeDefaultMode()
• Blank /ponytail queries without changing state
• The mode tracker in ponytail-mode-tracker.js handles all parsing, validation, and state management

Frequently Asked Questions

What happens if I type an invalid mode?

The hook validates arguments at lines 31‑55 in ponytail-mode-tracker.js. Unrecognized modes trigger an error response without changing your current configuration. Only lite, full, ultra, and off are accepted as runtime values.

Can I use /ponytail in any LLM host?

Yes. The command is registered globally via pi-extension/index.js, and the mode tracker hook processes prompts regardless of whether you use Claude, Gemini, or another supported host. The hook runs on every UserPromptSubmit event.

Where is my default mode actually stored?

writeDefaultMode() writes to the XDG-compliant configuration path, typically ~/.config/ponytail/config.json. The exact location respects your XDG_CONFIG_HOME environment variable as implemented in ponytail-config.js:76‑85.

Does /ponytail off delete my saved default?

No. The off command only clears the session flag via setMode() at line 70. Your persisted default remains intact in the config file and will automatically restore on your next session initialization.

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