How to Set Ponytail Mode: User Commands and Configuration Guide

Users set the Ponytail mode by typing /ponytail followed by the desired level (lite, full, ultra, or off) directly into the prompt, with optional persistence using the default subcommand.

Ponytail is an open-source LLM interaction framework that allows users to dynamically adjust instruction intensity through a configurable mode system. Setting the Ponytail mode requires no API calls or configuration file editing; instead, users control the system entirely through simple text commands embedded in their prompts.

Using the /ponytail Command Syntax

The primary interface for setting the Ponytail mode is the /ponytail text command, which the system detects via the UserPromptSubmit hook. The command accepts several variants and subcommands to control both temporary session behavior and permanent defaults.

Switching Modes for the Current Session

To activate a mode for the current session only, submit a prompt containing /ponytail followed by the target mode. Valid options include:

• lite – Minimal instruction injection
• full – Standard instruction set
• ultra – Maximum intensity instructions
• off – Disable Ponytail processing

Example input:

/ponytail ultra

When the hook in hooks/ponytail-mode-tracker.js detects this pattern, it calls setMode(mode) to write the mode flag to a temporary file that persists for the session duration. According to the source code at lines 64–77, the system then notifies the UI with a confirmation message indicating the new level.

Persisting a Default Mode Across Sessions

To make a mode survive application restarts, use the default subcommand syntax:

/ponytail default full

The parser in hooks/ponytail-mode-tracker.js (lines 34–45) detects the default keyword and validates the requested mode against the allowed list. Upon validation, it calls writeDefaultMode(mode), which is implemented in hooks/ponytail-config.js (lines 36–44). This function updates the user’s configuration file at $XDG_CONFIG_HOME/ponytail/config.json (or the platform-specific fallback), storing the value under the defaultMode key.

Deactivating Ponytail

Users can deactivate Ponytail in two ways:

1. Explicit command: Type /ponytail off to clear the current session mode.
2. Natural language: Submit the exact phrases stop ponytail or normal mode.

The deactivation detection logic resides in hooks/ponytail-config.js within the isDeactivationCommand function (lines 36–43). This utility normalizes the input string and checks for exact matches against the deactivation phrases. When triggered, the system invokes clearMode() from hooks/ponytail-runtime.js to remove the flag file and returns a confirmation that the mode is off.

How Mode Commands Are Processed Internally

Understanding the internal flow helps clarify how user text commands translate into runtime behavior across the Ponytail system.

Input Parsing in ponytail-mode-tracker.js

The entry point for all mode setting is the UserPromptSubmit hook defined in hooks/ponytail-mode-tracker.js. The hook reads incoming JSON from stdin, extracts the data.prompt field, and applies a case-insensitive regular expression to detect commands starting with /ponytail, @ponytail, or $ponytail. Lines 20–49 implement the parsing logic:

if (/^[/@$]ponytail/.test(prompt)) {
  const parts = prompt.split(/\s+/);
  const cmd = parts[0].replace(/^[@$]/, '/');
  const arg = parts[1] || '';

  // … decide which mode to activate
}

The code splits the prompt into components, normalizes alternative prefixes (@ or $) to /, and extracts the mode argument for further processing.

Runtime Flag Management via ponytail-runtime.js

Actual mode state changes are handled by utilities in hooks/ponytail-runtime.js. The setMode(mode) function writes the active mode to a temporary flag file, while clearMode() removes this file to disable processing. Other hooks, such as ponytail-subagent.js, query the current state via readMode() to determine which instruction set to inject into LLM calls. This architecture ensures that once a user sets the mode via text command, the configuration affects every subsequent generation until the session ends or the mode is changed.

Summary

• Text commands control everything: Users set the Ponytail mode by typing /ponytail <mode> directly into prompts—no API integration or manual config editing required.
• Session vs. persistence: Append default to the command (e.g., /ponytail default lite) to write the setting to $XDG_CONFIG_HOME/ponytail/config.json; otherwise, the mode lasts only for the current session.
• Flexible prefix support: The parser recognizes /, @, or $ prefixes interchangeably.
• Natural language deactivation: Phrases like stop ponytail or normal mode trigger the same cleanup routine as /ponytail off.
• Implementation files: Key functions reside in hooks/ponytail-mode-tracker.js (parsing), hooks/ponytail-runtime.js (flag management), and hooks/ponytail-config.js (persistence).

Frequently Asked Questions

Can I use alternative prefixes instead of the slash command?

Yes. The parser in hooks/ponytail-mode-tracker.js accepts @ponytail and $ponytail as valid alternatives to /ponytail. The code normalizes these prefixes to the standard slash format before processing the mode argument, allowing users to choose their preferred command style.

Where is the default mode stored when I use the default subcommand?

The writeDefaultMode function in hooks/ponytail-config.js persists the value to a JSON configuration file located at $XDG_CONFIG_HOME/ponytail/config.json on Linux systems, or the appropriate platform-specific equivalent on macOS and Windows. This file is created or merged during the write operation to preserve existing settings.

Why does /ponytail off not delete my default configuration?

The /ponytail off command clears only the temporary session flag via clearMode() in hooks/ponytail-runtime.js. It does not modify the persistent configuration file. To remove a saved default, you must explicitly set a new default mode (e.g., /ponytail default off) or manually edit the configuration JSON.

How do other hooks know which mode is currently active?

After a user sets the mode, the setMode() utility writes a flag file that serves as the session state. Downstream hooks like ponytail-subagent.js and the runtime controller call readMode() from hooks/ponytail-runtime.js before each LLM call to retrieve the current mode and select the appropriate instruction set for injection.

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