What Is the `hooks/` Directory in Ponytail? Understanding the Core Architecture

The hooks/ directory is the central lifecycle-hook integration layer that enables Ponytail to embed into multiple AI assistant platforms (Claude, Codex, Gemini, Pi) and react to platform-specific events.

If you're building or extending Ponytail, the hooks/ directory is where the magic happens. Located at the root of the DietrichGebert/ponytail repository, this directory contains everything needed to transform Ponytail from a simple library into a fully-featured plugin. The architecture centralizes hook definitions, runtime utilities, and configuration handling so that the same core logic works across every supported host environment.

Key Responsibilities of the hooks/ Directory

The hooks/ directory serves eight critical functions in Ponytail's architecture. Each responsibility is implemented through specific source files that work together as a cohesive system.

Expose Platform-Specific Hook Manifests

JSON manifest files map host-specific hook names to the commands Ponytail executes. These manifests live directly in hooks/:

• qoder-hooks.json — maps Qoder events like UserPromptSubmit to handler scripts
• claude-codex-hooks.json — defines hooks for Claude and Codex environments
• hooks.json — generic manifest for other compatible hosts

Here's how a hook binding looks in practice:

// hooks/qoder-hooks.json
{
  "hooks": {
    "command.execute.before": [
      {
        "hooks": [
          { "command": "node", "args": ["hooks/ponytail-mode-tracker.js"] }
        ]
      }
    ]
  }
}

Provide Runtime Utilities

ponytail-runtime.js is the core loader that detects the host environment, loads the appropriate manifest, and forwards events to the shared implementation. This utility ensures that platform-specific differences are abstracted away from the business logic.

// Example pattern from ponytail-runtime.js
const { loadPlugin } = require('./ponytail-runtime');

async function onCommandExecute(event) {
  const plugin = await loadPlugin({});
  await plugin['command.execute.before'](event);
}

Centralize Configuration and Mode Handling

ponytail-config.js acts as the single source of truth for Ponytail's behavior. It resolves the default mode, reads and writes user configuration, and provides helper predicates like isShellSafe() and isDeactivationCommand(). Every hook implementation imports this module, ensuring consistent configuration access across the entire system.

Track and Persist Mode State

ponytail-mode-tracker.js monitors activation and deactivation commands, then persists the chosen mode so that every host sees consistent state. When a user switches Ponytail modes, this script writes the update and ensures all connected environments reflect the change.

Enable Activation Helpers

ponytail-activate.js provides a convenience script that copies the hooks/ directory into a host's plugin folder. This simplifies installation across different AI assistant marketplaces.

# On Unix-like shells

node hooks/ponytail-activate.js

Build Instruction Sets for Extensions

ponytail-instructions.js generates a unified instruction set consumed by the Pi extension and other adapters. This ensures that extension-specific formatting and behavior remain consistent with the core Ponytail logic.

Support Status-Line Integration

Platform-native shell scripts provide visual indicators of Ponytail's current state:

• ponytail-statusline.sh — POSIX shell implementation
• ponytail-statusline.ps1 — PowerShell implementation

These scripts integrate with the host's command prompt to display the active Ponytail mode.

Enable Sub-Agent Entry Points

ponytail-subagent.js launches a separate Node process that maintains Ponytail state when the host spawns a sub-agent. This is critical for complex workflows where the primary assistant delegates tasks to specialized sub-agents that still need access to Ponytail functionality.

Architectural Benefits of the hooks/ Directory

By centralizing all hook-related code in one location, Ponytail achieves three major design goals:

• Code reuse — The same JavaScript handlers work across different host-specific manifests. No logic duplication between Claude and Codex adapters.
• Behavioral consistency — Mode resolution, configuration handling, and status-line updates work identically regardless of which plugin marketplace a user installs from.
• Clear extension points — New hosts only need to create a manifest file pointing to hooks/<manifest>.json. The runtime automatically loads appropriate handlers.

Summary

• The hooks/ directory is Ponytail's lifecycle-hook integration layer, enabling multi-platform AI assistant support.
• Hook manifests (qoder-hooks.json, claude-codex-hooks.json) map platform events to handler scripts.
• Runtime utilities (ponytail-runtime.js) abstract host detection and event dispatch.
• Configuration centralization (ponytail-config.js) ensures consistent behavior across all environments.
• Mode tracking (ponytail-mode-tracker.js) persists state across sessions and hosts.
• Activation scripts (ponytail-activate.js) simplify cross-platform installation.
• Status-line integration (shell and PowerShell scripts) provides visual state indicators.
• Sub-agent support (ponytail-subagent.js) extends functionality to delegated tasks.

Frequently Asked Questions

What file should I modify to add support for a new AI assistant platform?

Create a new JSON manifest file in hooks/ following the pattern of qoder-hooks.json or claude-codex-hooks.json. Map the platform's native hook names to the appropriate handler scripts in hooks/. You typically won't need to modify the JavaScript utilities—just reference them from your new manifest.

How does Ponytail maintain consistent state when I switch between Claude and Codex?

ponytail-mode-tracker.js writes mode changes to persistent storage, and ponytail-config.js provides the single source of truth that all hosts read from. When you activate Ponytail in one environment, the mode tracker updates the shared configuration, and the next environment you open will read that same state through ponytail-config.js.

Can I customize which hooks fire for a specific host?

Yes. Each manifest file in hooks/ independently defines which events trigger Ponytail actions. You can include or exclude specific hook entries in your custom manifest, or point events to different handler scripts while still using the shared runtime utilities for consistency.

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