# How to Set Ponytail Mode: User Commands and Configuration Guide

> Easily set Ponytail mode with simple user commands like /ponytail lite or /ponytail full. Learn configuration and persistence options for the DietrichGebert/ponytail repository.

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

---

**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:

```text
/ponytail ultra

```

When the hook in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/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:

```text
/ponytail default full

```

The parser in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-mode-tracker.js)

The entry point for all mode setting is the **UserPromptSubmit** hook defined in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/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:

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

Actual mode state changes are handled by utilities in [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) (parsing), [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) (flag management), and [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-subagent.js) and the runtime controller call `readMode()` from [`hooks/ponytail-runtime.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-runtime.js) before each LLM call to retrieve the current mode and select the appropriate instruction set for injection.