# How to Use Ponytail Commands in Different AI Hosts: Claude, Gemini, and OpenCode Guide

> Master Ponytail commands across Claude, Gemini, and OpenCode. This guide shows how to use the Pi extension runtime for unified AI assistant interaction. Learn to register slash commands like /ponytail ultra.

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

---

**Ponytail exposes a unified command surface across AI assistants through the Pi extension runtime, using declarative TOML manifests that Claude, Gemini, OpenCode, and other hosts parse to register slash commands like `/ponytail ultra` or `/ponytail-review`.**

Ponytail is an open-source AI assistant extension that standardizes command interfaces across multiple host environments. By implementing a host-agnostic command registration system in the [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) repository, it enables consistent **mode management** and **skill invocation** whether you are using Claude Desktop, the Gemini CLI, or OpenCode.

## Architecture of Cross-Host Command Registration

The core command registration logic lives in [[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js), where the Pi runtime exposes the `pi.registerCommand` method to declare available operations:

```javascript
// Registration occurs at lines 14-48 in pi-extension/index.js
pi.registerCommand("ponytail", { ... });
pi.registerCommand("ponytail-review", { ... });
pi.registerCommand("ponytail-audit", { ... });
pi.registerCommand("ponytail-gain", { ... });
pi.registerCommand("ponytail-debt", { ... });
pi.registerCommand("ponytail-help", { ... });

```

Each registered command maps to a **declarative manifest** in the `commands/` directory. Host-specific adapters—such as those for Claude, Gemini, and OpenCode—parse these manifests to expose native slash commands without duplicating JavaScript logic. This architecture ensures that adding a new host requires only a TOML parser, not a full reimplementation of command handlers.

## Host-Specific TOML Manifests

Ponytail separates command definitions from host implementations using TOML configuration files. These manifests declare command names, descriptions, and aliases that any compatible host can consume:

- [[`commands/ponytail.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail.toml) — Base mode management commands
- [[`commands/ponytail-review.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-review.toml) — Code review skill
- [[`commands/ponytail-audit.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-audit.toml) — Security audit skill  
- [[`commands/ponytail-gain.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-gain.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-gain.toml) — Knowledge gain tracking
- [[`commands/ponytail-debt.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-debt.toml) — Technical debt identification
- [[`commands/ponytail-help.toml`](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml)](https://github.com/DietrichGebert/ponytail/blob/main/commands/ponytail-help.toml) — Help documentation

When a host like Claude or Gemini loads the extension, it scans these files to populate its slash-command menu with the appropriate labels and triggers.

## Using Ponytail Commands in Claude

Claude's adapter reads the TOML manifests to register native slash commands. You can manage Ponytail's operational modes or invoke specific skills directly in the chat interface:

```bash
/ponytail lite          # Switch to lite mode for quick responses

/ponytail full          # Switch to full mode with detailed reasoning

/ponytail ultra         # Switch to ultra mode for maximum depth

/ponytail status        # Display the currently active mode

/ponytail default full  # Set full as the default mode for new sessions

/ponytail-review        # Invoke the code review skill

/ponytail-audit         # Invoke the security audit skill

/ponytail-gain          # Track knowledge acquisition

/ponytail-debt          # Identify technical debt

/ponytail-help          # Display command reference

```

## Using Ponytail Commands in Gemini

The Gemini CLI utilizes the same underlying TOML files, enabling consistent syntax across hosts. Append Ponytail commands to your existing prompts:

```bash

# Execute a prompt with ultra mode enabled

gi implement quicksort /ponytail ultra

# Invoke the audit skill after code generation

gi review this function /ponytail-audit

```

## Using Ponytail Commands in OpenCode

OpenCode reads the manifests from `.opencode/command/*.md` but exposes an identical command surface to maintain cross-platform consistency:

```bash
> /ponytail full
> /ponytail-review
> /ponytail-gain

```

## Command Processing Pipeline

When a user invokes a command, the Pi extension handles execution through `parsePonytailCommand` (implemented at lines 39-58 in [[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)). The pipeline operates as follows:

1. **Mode Commands** — For inputs like `lite`, `full`, `ultra`, `status`, or `default <mode>`, the extension updates the internal state via [[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js), persists the change using `writeDefaultMode`, and emits a status-bar update.

2. **Skill Commands** — For skill invocations (`ponytail-review`, `ponytail-audit`, etc.), the extension uses `sendAlias` to dispatch a `/skill:` message to the LLM backend, routing the request to the appropriate handler.

The [[`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) file provides **mode-specific system prompts** that are injected during the `before_agent_start` hook, ensuring the model adopts the correct "lazy senior developer" persona based on the active mode.

## Summary

- Ponytail registers six core commands via [[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) using the Pi runtime's `registerCommand` API.
- **TOML manifest files** in the `commands/` directory provide host-agnostic definitions that Claude, Gemini, OpenCode, Hermes, and Copilot adapters consume.
- **Mode management** (lite/full/ultra) persists across sessions using [[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js).
- **Skill commands** delegate to the LLM backend via `sendAlias` with `/skill:` routing.
- The instruction builder in [[`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js) dynamically adjusts system prompts based on the active mode.

## Frequently Asked Questions

### How do I add Ponytail commands to a custom AI host?

Implement a TOML parser in your host adapter that reads the files in the [`commands/`](https://github.com/DietrichGebert/ponytail/tree/main/commands) directory. Map each TOML entry to your host's native command structure (slash commands, chat commands, or function calling). Then initialize the Pi runtime and import [[`pi-extension/index.js`](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js)](https://github.com/DietrichGebert/ponytail/blob/main/pi-extension/index.js) to register the handlers. No modifications to the core Ponytail code are required.

### Are Ponytail commands identical across Claude and Gemini?

Yes. Both hosts consume the same TOML manifest files, ensuring that command names, descriptions, and behaviors remain consistent. The syntax differs only in how you invoke the host CLI—Claude uses `/command` syntax in the chat UI, while Gemini appends commands to the prompt—but the underlying functionality and available modes are identical.

### What is the difference between mode commands and skill commands?

**Mode commands** (`/ponytail lite`, `/ponytail full`, `/ponytail ultra`) adjust the operational behavior of the AI assistant by updating the system prompt via [[`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js). **Skill commands** (`/ponytail-review`, `/ponytail-audit`) trigger specific workflows that send `/skill:` messages to the backend using `sendAlias`, invoking specialized analysis routines without changing the global mode.

### How does Ponytail persist mode settings across chat sessions?

When you execute `/ponytail default <mode>`, the extension calls `writeDefaultMode` from [[`hooks/ponytail-config.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-config.js) to write the preference to persistent storage. On subsequent session starts, the `before_agent_start` hook reads this value and automatically injects the corresponding instructions from [[`hooks/ponytail-instructions.js`](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js)](https://github.com/DietrichGebert/ponytail/blob/main/hooks/ponytail-instructions.js), restoring your preferred operating mode.