How Review Mode Works in Ponytail and Why It Is Session-Only

Review mode in Ponytail injects the ponytail-review skill instructions into every LLM prompt by dynamically loading SKILL.md from the cache, and it remains strictly session-only because the active mode is stored in the transient global variable _current_mode that is never persisted to disk or environment variables.

Ponytail, an open-source LLM gateway maintained by DietrichGebert, provides a specialized review mode for on-demand code analysis. This runtime configuration temporarily modifies AI behavior by prepending specific review instructions to each prompt, ensuring temporary over-engineering checks without affecting long-term user settings.

How Review Mode Injects Context

The review mode implementation centers on runtime context injection handled in the package initialization file.

The Runtime Configuration System

In __init__.py, line 13 defines review as a distinct runtime configuration option within the CONFIG_MODES set:

CONFIG_MODES = RUNTIME_MODES | {"review"}

This classification distinguishes review mode from persistent configuration values, signaling that it should be handled ephemerally.

Loading the Skill File

The build_injected_context function ( lines 10-15 and 110-114 in __init__.py) checks the active configuration and loads the skill definition when configured == "review":

def build_injected_context(mode: str | None = None) -> str:
    ...
    if configured == "review":
        body = REVIEW_SKILL.read_text(encoding="utf-8")
        return f"PONYTAIL MODE ACTIVE — level: review\n\n{_strip_frontmatter(body)}"

The REVIEW_SKILL constant points to the cache path /cache/repos/github.com/DietrichGebert/ponytail/main/skills/ponytail-review/SKILL.md, which contains the markdown instructions stripped of frontmatter before injection.

Activating Review Mode for the Current Session

Users trigger review mode through interfaces that update the global state without touching persistent storage.

Slash Command Interface

The /ponytail-review command defined in commands/ponytail-review.toml is processed by the rewrite_gateway_command function (lines 54-64 in __init__.py). This routes to _handle_mode_command, which updates the global state:

# Declared on line 27 of __init__.py

_current_mode: str | None = None

def _handle_mode_command(mode: str) -> None:
    global _current_mode
    _current_mode = mode  # Lines 66-78 handle this update

Environment Variable Override

For single invocations, you can start Ponytail with review mode active:

PONYTAIL_DEFAULT_MODE=review ponytail

The application reads this environment variable once at startup to set the default, but because _current_mode remains a runtime-only variable, the mode still does not persist beyond the current process lifetime.

Why Review Mode Is Session-Only

The ephemeral nature of review mode stems from intentional architectural limitations that prevent persistence.

Ephemeral Global State

The active mode lives exclusively in the _current_mode global variable declared on line 27 of __init__.py. The _handle_mode_command function (lines 66-78) modifies this variable in-process without serializing to the filesystem or exporting to shell environment variables. When the Python process terminates, _current_mode is garbage collected, causing Ponytail to revert to the standard default mode on the next launch.

No Persistence by Design

Unlike user preferences stored in configuration files, review mode is designed for ad-hoc over-engineering checks that should not outlive the current conversation. The implementation deliberately avoids writing to ~/.ponytail/config or similar persistent stores to prevent temporary analytical contexts from accidentally becoming permanent behavior modifiers. This ensures developers must explicitly activate review mode for each session requiring code review assistance.

Summary

• Context injection occurs via build_injected_context in __init__.py, which loads skills/ponytail-review/SKILL.md from the cache when review mode is active.
• Activation methods include the /ponytail-review slash command (handled by rewrite_gateway_command and _handle_mode_command) or temporary environment variables.
• Session-only storage results from using the _current_mode global variable (line 27) that exists only in memory and is never persisted.
• Safety design prevents temporary review contexts from polluting long-term configuration, requiring explicit opt-in for each session.

Frequently Asked Questions

How do I enable review mode in Ponytail?

You enable review mode for the current session by issuing the /ponytail-review slash command, which calls _handle_mode_command to update the _current_mode global variable in __init__.py. Alternatively, prepend PONYTAIL_DEFAULT_MODE=review to your startup command to enable it for a single invocation. Both methods affect only the current process and automatically reset when the application terminates.

Why doesn't review mode persist after I close the application?

Review mode is intentionally session-only because the implementation stores state in the _current_mode global variable rather than writing to configuration files or environment variables. According to the source code in __init__.py (lines 27 and 66-78), when the process ends, this variable is destroyed, forcing a return to the default mode on the next startup to prevent accidental persistent changes to AI behavior.

What file contains the review instructions sent to the LLM?

The review instructions are stored in skills/ponytail-review/SKILL.md within the repository structure, which is accessed at runtime from the cache path /cache/repos/github.com/DietrichGebert/ponytail/main/skills/ponytail-review/SKILL.md. The build_injected_context function reads this file and uses _strip_frontmatter to remove metadata before injecting the content into LLM prompts.

Can I use review mode alongside other Ponytail modes?

No, review mode operates as an exclusive runtime configuration. The _current_mode variable holds a single string value (such as "review"), and the CONFIG_MODES definition in __init__.py treats review as a distinct state. You must explicitly switch between modes using the appropriate slash commands or environment variables for each session, as the system does not support mode stacking or concurrent activation.

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