Environment Variables Used by Ponytail to Detect the Host Platform

Ponytail does not rely on environment variables to detect the host platform; instead, it uses Python's built-in os.name property to identify Windows versus POSIX systems, then applies platform-specific environment variables such as APPDATA or XDG_CONFIG_HOME solely for configuration path resolution after the OS has been determined.

Ponytail is an open-source project by DietrichGebert designed to manage cross-platform configuration directories and runtime modes. While many applications query environment variables to determine whether they are running on Windows, macOS, or Linux, Ponytail takes a different architectural approach by leveraging the standard library for OS detection before consulting environment variables for path configuration.

How Ponytail Detects the Host Platform Without Environment Variables

According to the source code in ponytail/__init__.py, Ponytail determines the operating system through Python’s os.name rather than environment variables. This property returns "nt" for Windows and "posix" for Unix-like systems.

In lines 45-49 of ponytail/__init__.py, the codebase checks os.name to decide which default configuration directory to use. This logic executes before any environment variable is read, ensuring the platform is identified via the standard library’s reliable mechanism rather than external configuration.

import os
from pathlib import Path

# Platform detection as implemented in Ponytail

if os.name == "nt":
    # Windows-specific logic

    config_dir = Path(os.getenv("APPDATA", Path.home() / "AppData" / "Roaming")) / "ponytail"
else:
    # POSIX-compatible logic (Linux/macOS)

    config_dir = Path(os.getenv("XDG_CONFIG_HOME", Path.home() / ".config")) / "ponytail"

Platform-Specific Environment Variables for Configuration Paths

Once os.name identifies the platform, Ponytail uses environment variables only to override default configuration directories. These variables do not influence the detection logic itself, but rather the final path construction.

XDG_CONFIG_HOME for Linux and macOS

On non-Windows systems, Ponytail respects the XDG Base Directory Specification. If XDG_CONFIG_HOME is set, Ponytail uses it as the parent directory for its configuration folder. If unset, it defaults to ~/.config/ponytail.

# Override the default config location on Linux or macOS

export XDG_CONFIG_HOME="/custom/config/path"

# Result: Ponytail will use /custom/config/path/ponytail

APPDATA for Windows

On Windows (when os.name == "nt"), Ponytail looks for the APPDATA environment variable to locate the roaming AppData directory. If this variable is unavailable, it falls back to constructing the path from the user's home directory.

# Override the AppData location on Windows

set APPDATA=C:\Users\Me\CustomAppData

# Result: Ponytail will use C:\Users\Me\CustomAppData\ponytail

Runtime and Benchmark Environment Variables

Beyond platform path configuration, Ponytail recognizes several other environment variables that control behavior across all operating systems.

PONYTAIL_DEFAULT_MODE

Line 53 of ponytail/__init__.py reads the PONYTAIL_DEFAULT_MODE variable to set the initial runtime mode. Valid options include lite, full, ultra, off, and review. This setting is platform-agnostic and affects how Ponytail behaves regardless of the host OS.

# Set the default mode before running Ponytail

export PONYTAIL_DEFAULT_MODE=ultra

PONYTAIL_PLUGIN_DIR and PONYTAIL_TMPL for Benchmarks

The benchmark scripts in benchmarks/agentic/ use additional environment variables for temporary overrides. Lines 28-30 of benchmarks/agentic/tasks.py reference PONYTAIL_TMPL to specify a template repository for benchmark tasks. Similarly, lines 210-215 of benchmarks/agentic/run.py use PONYTAIL_PLUGIN_DIR to override the plugin directory location during test runs.

# Used for benchmark execution to point to local resources

export PONYTAIL_TMPL=my-local-template
export PONYTAIL_PLUGIN_DIR=/tmp/ponytail-plugins

These benchmark-specific variables are primarily used in development and testing workflows rather than standard production deployments.

Source Code Implementation Details

The actual implementation of platform detection and environment variable handling is concentrated in specific source files:

• ponytail/__init__.py (lines 45-49): Contains the os.name check and the conditional logic for selecting between APPDATA and XDG_CONFIG_HOME.
• ponytail/__init__.py (line 53): Reads PONYTAIL_DEFAULT_MODE from the environment.
• benchmarks/agentic/tasks.py (lines 28-30): Demonstrates usage of PONYTAIL_TMPL for benchmark task templates.
• benchmarks/agentic/run.py (lines 210-215): Shows temporary override of PONYTAIL_PLUGIN_DIR during benchmark execution.

Summary

• Platform detection in Ponytail relies on os.name (returning "nt" for Windows or "posix" for Linux/macOS), not environment variables.
• XDG_CONFIG_HOME overrides configuration directories on Linux and macOS systems.
• APPDATA provides the roaming profile directory path on Windows systems only.
• PONYTAIL_DEFAULT_MODE sets the runtime mode across all platforms.
• PONYTAIL_PLUGIN_DIR and PONYTAIL_TMPL are reserved for benchmark and testing scenarios.

Frequently Asked Questions

Does Ponytail use environment variables to detect Windows or Linux?

No. According to the source code in ponytail/__init__.py, Ponytail uses Python's standard os.name property to detect the host platform. Environment variables like APPDATA or XDG_CONFIG_HOME are only consulted after the platform has been identified to determine where to store configuration files.

What is the difference between XDG_CONFIG_HOME and APPDATA in Ponytail?

XDG_CONFIG_HOME is used on POSIX-compliant systems (Linux and macOS) to override the default ~/.config directory, following the XDG Base Directory Specification. APPDATA is used exclusively on Windows (when os.name == "nt") to locate the roaming application data folder. Both serve the same purpose of customizing the configuration path, but each applies to a different operating system.

How do I change Ponytail's default runtime mode?

Set the PONYTAIL_DEFAULT_MODE environment variable to one of the supported values: lite, full, ultra, off, or review. This variable is read at initialization (line 53 of ponytail/__init__.py) and applies across all platforms, affecting how Ponytail processes and executes tasks.

What are PONYTAIL_PLUGIN_DIR and PONYTAIL_TMPL used for?

These variables are specific to Ponytail's benchmark suite. PONYTAIL_TMPL, referenced in benchmarks/agentic/tasks.py, points to a template repository for benchmark tasks. PONYTAIL_PLUGIN_DIR, used in benchmarks/agentic/run.py, allows tests to temporarily override the plugin search path. Neither variable affects standard platform detection or production runtime behavior.

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