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

> Understand how Ponytail's review mode injects skill instructions into LLM prompts and why it's session-only due to transient global variables. Learn more now.

- Repository: [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail)
- Tags: deep-dive
- Published: 2026-08-30

---

**Review mode in Ponytail injects the ponytail-review skill instructions into every LLM prompt by dynamically loading [`SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py), line 13 defines review as a distinct runtime configuration option within the `CONFIG_MODES` set:

```python
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`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)) checks the active configuration and loads the skill definition when `configured == "review"`:

```python
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`](https://github.com/DietrichGebert/ponytail/blob/main//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`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml) is processed by the `rewrite_gateway_command` function (lines 54-64 in [`__init__.py`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py)). This routes to `_handle_mode_command`, which updates the global state:

```python

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

```bash
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`](https://github.com/DietrichGebert/ponytail/blob/main/__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`](https://github.com/DietrichGebert/ponytail/blob/main/__init__.py), which loads [`skills/ponytail-review/SKILL.md`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main/__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`](https://github.com/DietrichGebert/ponytail/blob/main/__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`](https://github.com/DietrichGebert/ponytail/blob/main/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`](https://github.com/DietrichGebert/ponytail/blob/main//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`](https://github.com/DietrichGebert/ponytail/blob/main/__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.