ponytail-python

Ponytail

He says nothing. He writes one line. It works.

Ponytail is a lazy senior dev mode for AI agents. Before writing code, it stops at the first rung that holds:

1. Does this need to exist?   → no: skip it (YAGNI)
2. Stdlib does it?            → use it
3. Native platform feature?   → use it
4. Installed dependency?      → use it
5. One line?                  → one line
6. Only then: the minimum that works

~54% less code (up to 94%) · ~20% cheaper · ~27% faster · 100% safe

Measured on real Claude Code sessions editing a real open-source repo (FastAPI + React), against the same agent with no skill.

How it works

This is a Python package that provides:

• Instructions: Builds the lazy-dev ruleset for 3 intensity levels (lite, full, ultra)
• Config: Resolves mode from env vars → config file → defaults (platform-aware: Windows, macOS, Linux)
• Skills: SKILL.md files defining ponytail, ponytail-review, ponytail-audit, ponytail-debt, ponytail-gain, ponytail-help
• Commands: TOML command definitions for agent hosts
• CLI: ponytail command to view instructions, list skills, check/set config
• MCP server: (optional) serves instructions over stdio as a prompt + tool

Install

pip install ponytail
# or from source:
pip install -e .

Usage

CLI

# Show instructions for the default mode
ponytail

# Show instructions for a specific mode
ponytail ultra

# List available skills
ponytail --list

# Check config
ponytail --config

# Set default mode
ponytail --set lite

Python API

from ponytail import get_instructions, resolve_mode
from ponytail.config import get_default_mode, normalize_mode
from ponytail.skills import list_skills, get_skill_content

# Get instructions for a specific mode
instructions = get_instructions("ultra")

# Resolve a mode
mode = resolve_mode("lite")  # -> "lite"

# List available skills
skills = list_skills()

# Read a skill
content = get_skill_content("ponytail-review")

MCP Server

# Install with MCP support
pip install 'ponytail[mcp]'

# Run the MCP server over stdio
python -m ponytail.mcp_server

Configuration

Resolution order:

1. PONYTAIL_DEFAULT_MODE environment variable
2. Config file:
   • $XDG_CONFIG_HOME/ponytail/config.json
   • ~/.config/ponytail/config.json (Linux/macOS)
   • %APPDATA%\ponytail\config.json (Windows)
3. full (default)

Config file format:

{ "defaultMode": "lite" }

Valid modes: off, lite, full, ultra, review

Skills

The Ladder

The ladder is a reflex, not a research project. Two rungs work → take the higher one and move on. The first lazy solution that works is the right one.

Never simplify away: input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility basics, anything explicitly requested.

Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind (assert-based self-check or one small test file; no frameworks, no fixtures). Trivial one-liners need no test.

中文文档

中文使用说明请见 README.zh.md。

License

MIT