# How to Use Ponytail Commands to Switch Modes or Deactivate It

> Learn how to use Ponytail commands to effortlessly switch between lite, full, and ultra modes or deactivate it with simple commands like /ponytail off or stop ponytail.

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

---

**Use the `/ponytail <mode>` command to switch between `lite`, `full`, and `ultra` modes, or type `/ponytail off`, `stop ponytail`, or `normal mode` to deactivate Ponytail for the current session.**

Ponytail is an open-source coding assistant that adapts its behavior through a runtime mode system that controls code generation aggressiveness. When you need to adjust how strictly it applies the "lazy senior dev" optimizations or turn it off entirely, Ponytail provides several commands and configuration options. Understanding how to use Ponytail commands to switch modes or deactivate it ensures you maintain precise control over the tool's intervention levels.

## How Ponytail Resolves the Active Mode

Ponytail determines its execution mode through a cascading resolution system implemented in [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js). The system checks three sources in strict priority order:

1. **Environment variable** – `PONYTAIL_DEFAULT_MODE` overrides everything when set to `off`, `lite`, `full`, or `ultra`.
2. **User configuration file** – `~/.config/ponytail/config.json` on Linux/macOS or `%APPDATA%\ponytail\config.json` on Windows, containing a `defaultMode` key.
3. **Built-in fallback** – Defaults to `full` mode if no other source is found.

Once resolved, [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) stores the active mode in a temporary flag file within the repository's `.ponytail` directory. The initialization logic in [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) then reads this flag to configure command behavior and determine how aggressively to apply the YAGNI → stdlib → native → one-line → minimum ladder.

## Switching Modes with the /ponytail Command

The primary interface for mode switching is defined in [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml). Use the `/ponytail` slash command followed by your desired intensity:

```text
/ponytail lite        # Minimal intervention, builds only explicit requests

/ponytail ultra       # Aggressive "deletion-before-addition" optimizations  

/ponytail             # Alias for full mode (default behavior)

/ponytail full        # Explicit standard mode

```

Omitting the mode argument defaults to `full`, which implements the standard optimization ladder.

## Deactivating Ponytail for the Current Session

To completely disable Ponytail without changing persistent settings, use any of the three deactivation syntaxes documented in [`commands/ponytail-help.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml):

```text
/ponytail off         # Official command to disable Ponytail

stop ponytail         # Natural language synonym

normal mode           # Alternative phrasing to return to standard behavior

```

These commands set the session mode to `off`, preventing [`ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/ponytail-activate.js) from injecting mode-aware behavior into subsequent commands.

## Persisting Mode Settings Across Sessions

For permanent configuration, set the `PONYTAIL_DEFAULT_MODE` environment variable in your shell profile:

```bash
export PONYTAIL_DEFAULT_MODE=lite

```

Alternatively, create a JSON configuration file at the appropriate path for your operating system. On Linux or macOS:

```bash
mkdir -p ~/.config/ponytail

```

Then create `~/.config/ponytail/config.json`:

```json
{
  "defaultMode": "ultra"
}

```

On Windows, use `%APPDATA%\ponytail\config.json`. The configuration file takes precedence over the environment variable, while slash commands override both for the current session only.

## Checking the Current Mode

To verify which mode is active, invoke the help command:

```text
/ponytail-help

```

This command, defined in [`commands/ponytail-help.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml), displays a quick-reference card that prints the currently active mode at the top of the output, showing the resolved setting from the precedence chain.

## Summary

- Ponytail supports four modes: `off`, `lite`, `full`, and `ultra`, controlled by a cascade of environment variables, config files, and defaults processed by [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).
- Switch modes instantly using `/ponytail <mode>` as implemented in [`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml).
- Deactivate Ponytail immediately with `/ponytail off`, `stop ponytail`, or `normal mode`.
- Persist preferences using `PONYTAIL_DEFAULT_MODE` or `~/.config/ponytail/config.json`.
- The mode tracker in [`hooks/ponytail-mode-tracker.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-mode-tracker.js) maintains session state, while [`hooks/ponytail-activate.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-activate.js) applies the behavior changes to commands.

## Frequently Asked Questions

### What is the difference between Ponytail's lite and ultra modes?

Lite mode restricts Ponytail to building only what is explicitly requested without aggressive optimizations, while ultra mode enables the most aggressive "deletion-before-addition" strategy, maximizing code reduction through the full YAGNI ladder. The default `full` mode provides balanced optimizations suitable for most development workflows.

### Why does my mode setting keep resetting when I start a new session?

Ponytail stores session mode in a temporary flag file under the `.ponytail` directory that resets when the session ends. To maintain settings across sessions, you must set `PONYTAIL_DEFAULT_MODE` or configure `~/.config/ponytail/config.json` as read by [`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) during initialization.

### Can I use Ponytail in normal mode without uninstalling it?

Yes. Typing `normal mode` or `/ponytail off` deactivates Ponytail for the current session without removing the tool or altering persistent configuration. This sets the mode flag to `off` until you explicitly reactivate it with `/ponytail <mode>`.

### Which configuration source takes precedence if I have multiple settings?

The resolution order is: slash commands (highest priority), then `~/.config/ponytail/config.json`, then `PONYTAIL_DEFAULT_MODE` environment variable, then the built-in default of `full` (lowest priority). Commands always override persistent settings for the current session only.