Hooks

Where it lives

• hooks/ponytail-activate.jsGitHub ↗
  Read the script

  #!/usr/bin/env node
  // ponytail — Claude Code SessionStart activation hook (also Codex, Copilot,
  // Grok and Cursor sessionStart)
  //
  // Runs on every session start:
  //   1. Writes flag file at $CLAUDE_CONFIG_DIR/.ponytail-active (defaults to ~/.claude; statusline reads this)
  //   2. Emits ponytail ruleset as hidden SessionStart context
  //   3. Detects missing statusline config and emits setup nudge
  
  const fs = require('fs');
  const path = require('path');
  const { getDefaultMode, getClaudeDir, isShellSafe } = require('./ponytail-config');
  const { getPonytailInstructions } = require('./ponytail-instructions');
  const {
    clearMode,
    cursorRuleNotice,
    cursorRulePath,
    isCodex,
    isCopilot,
    isCursor,
    setMode,
    writeHookOutput,
  } = require('./ponytail-runtime');
  
  const claudeDir = getClaudeDir();
  const settingsPath = path.join(claudeDir, 'settings.json');
  
  const mode = getDefaultMode();
  
  // "off" mode — skip activation entirely, don't write flag or emit rules
  if (mode === 'off') {
    clearMode();
    const hookOutput = (isCodex || isCopilot || isCursor) ? '' : 'OK';
    writeHookOutput('SessionStart', 'off', hookOutput);
    process.exit(0);
  }
  
  // Cursor with the always-on rule in the workspace: the rule already carries the
  // ruleset and would contradict any other level, so leave the flag alone and
  // hand the model a one-line notice instead of a second copy (#817).
  if (isCursor) {
    const rule = cursorRulePath();
    if (rule) {
      try {
        writeHookOutput('SessionStart', mode, cursorRuleNotice(rule));
      } catch (e) {
        // Silent fail — stdout closed/EPIPE at hook exit must not surface as a hook failure
      }
      process.exit(0);
    }
  }
  
  // 1. Write flag file
  try {
    setMode(mode);
  } catch (e) {
    // Silent fail -- flag is best-effort, don't block the hook
  }
  
  // 2. Emit the ponytail ruleset, filtered to the active intensity level.
  let output = getPonytailInstructions(mode);
  
  // 3. Detect missing statusline config — nudge Claude to help set it up
  if (!isCodex && !isCopilot && !isCursor) try {
    let hasStatusline = false;
    if (fs.existsSync(settingsPath)) {
      // Strip UTF-8 BOM some editors prepend on Windows (breaks JSON.parse)
      const raw = fs.readFileSync(settingsPath, 'utf8').replace(/^\uFEFF/, '');
      const settings = JSON.parse(raw);
      if (settings.statusLine) {
        hasStatusline = true;
      }
    }
  
    // Nudge at most once — the flag file marks that the user has already seen
    // (and implicitly declined) the statusline setup offer. Repeating it every
    // session start turns a helpful hint into a nag.
    const nudgeFlagPath = path.join(claudeDir, '.ponytail-statusline-nudged');
    if (!hasStatusline && !fs.existsSync(nudgeFlagPath)) {
      try { fs.writeFileSync(nudgeFlagPath, ''); } catch (e) { /* best-effort */ }
      const isWindows = process.platform === 'win32';
      const scriptName = isWindows ? 'ponytail-statusline.ps1' : 'ponytail-statusline.sh';
      const scriptPath = path.join(__dirname, scriptName);
      if (isShellSafe(scriptPath)) {
        const command = isWindows
          ? `powershell -ExecutionPolicy Bypass -File "${scriptPath}"`
          : `bash "${scriptPath}"`;
        const statusLineSnippet =
          '"statusLine": { "type": "command", "command": ' + JSON.stringify(command) + ' }';
        output += "\n\n" +
          "STATUSLINE SETUP NEEDED: The ponytail plugin includes a statusline badge showing active mode " +
          "(e.g. [PONYTAIL], [PONYTAIL:ULTRA]). It is not configured yet. " +
          "To enable, add this to " + settingsPath + ": " +
          statusLineSnippet + " " +
          "Proactively offer to set this up for the user on first interaction.";
      } else {
        // ponytail: install path has shell metacharacters — don't embed it in a
        // command snippet; have the agent wire it up by hand instead.
        output += "\n\n" +
          "STATUSLINE SETUP NEEDED: The ponytail plugin includes a statusline badge showing active mode. " +
          "Its install path contains characters unsafe to embed in a shell command, so configure it manually: " +
          "add a statusLine command of type \"command\" that runs " + scriptName +
          " from the plugin's hooks directory to " + settingsPath + ", quoting/escaping the path for your shell. " +
          "Proactively offer to set this up for the user on first interaction.";
      }
    }
  } catch (e) {
    // Silent fail — don't block session start over statusline detection
  }
  
  try {
    writeHookOutput('SessionStart', mode, output);
  } catch (e) {
    // Silent fail — stdout closed/EPIPE at hook exit must not surface as a hook failure
  }
  

• hooks/ponytail-config.jsGitHub ↗
  Read the script

  #!/usr/bin/env node
  // ponytail — shared configuration resolver
  //
  // Resolution order for default mode:
  //   1. PONYTAIL_DEFAULT_MODE environment variable
  //   2. Config file defaultMode field:
  //      - $XDG_CONFIG_HOME/ponytail/config.json (any platform, if set)
  //      - ~/.config/ponytail/config.json (macOS / Linux fallback)
  //      - %APPDATA%\ponytail\config.json (Windows fallback)
  //   3. 'full'
  
  const fs = require('fs');
  const path = require('path');
  const os = require('os');
  
  const DEFAULT_MODE = 'full';
  const VALID_MODES = ['off', 'lite', 'full', 'ultra', 'review'];
  const RUNTIME_MODES = ['off', 'lite', 'full', 'ultra'];
  
  function normalizeMode(mode) {
    if (typeof mode !== 'string') return null;
    const normalized = mode.trim().toLowerCase();
    return RUNTIME_MODES.includes(normalized) ? normalized : null;
  }
  
  function normalizeConfigMode(mode) {
    if (typeof mode !== 'string') return null;
    const normalized = mode.trim().toLowerCase();
    return VALID_MODES.includes(normalized) ? normalized : null;
  }
  
  function normalizePersistedMode(mode) {
    return normalizeMode(mode) || normalizeConfigMode(mode);
  }
  
  // "stop ponytail" / "normal mode" turn ponytail off, but only as a standalone
  // command. Matching the phrase anywhere in the message turned it off mid-task
  // for ordinary requests like "add a normal mode toggle" — so require the whole
  // message to be the command, ignoring case and trailing punctuation.
  function isDeactivationCommand(text) {
    const t = String(text || '').trim().toLowerCase().replace(/[.!?\s]+$/, '');
    return t === 'stop ponytail' || t === 'normal mode';
  }
  
  // ponytail: only embed the plugin install path in a statusline shell command when
  // it's made of ordinary path characters. An allowlist beats escaping every shell's
  // metacharacters; a hostile clone path (quotes, &, $, backtick, ;, etc.) falls back
  // to manual setup instead. Allows : \ / for normal Windows and POSIX paths. Full
  // per-shell escaper only if a real need appears.
  function isShellSafe(p) {
    return typeof p === 'string' && /^[A-Za-z0-9 _.\-:/\\~]+$/.test(p);
  }
  
  function getConfigDir() {
    if (process.env.XDG_CONFIG_HOME) {
      return path.join(process.env.XDG_CONFIG_HOME, 'ponytail');
    }
    if (process.platform === 'win32') {
      return path.join(
        process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Roaming'),
        'ponytail'
      );
    }
    return path.join(os.homedir(), '.config', 'ponytail');
  }
  
  function getConfigPath() {
    return path.join(getConfigDir(), 'config.json');
  }
  
  function getClaudeDir() {
    // ponytail: CLAUDE_CONFIG_DIR overrides ~/.claude, matching Claude Code.
    return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
  }
  
  function getDefaultMode() {
    // 1. Environment variable (highest priority)
    const envMode = process.env.PONYTAIL_DEFAULT_MODE;
    // ponytail: a default must be a runtime level (off/lite/full/ultra); review is
    // a session-only mode, never a valid default (#377). Validate against
    // RUNTIME_MODES so a stray env var or config can't make review the default.
    if (envMode && RUNTIME_MODES.includes(envMode.toLowerCase())) {
      return envMode.toLowerCase();
    }
  
    // 2. Config file
    try {
      const configPath = getConfigPath();
      // Strip UTF-8 BOM (common on Windows-saved files) so JSON.parse doesn't choke
      const config = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, ''));
      if (config.defaultMode && RUNTIME_MODES.includes(config.defaultMode.toLowerCase())) {
        return config.defaultMode.toLowerCase();
      }
    } catch (e) {
      // Config file doesn't exist or is invalid — fall through
    }
  
    // 3. Default
    return DEFAULT_MODE;
  }
  
  // Silence the pi "Ponytail loaded" startup toast while keeping ponytail active.
  // PONYTAIL_QUIET_STARTUP=1 (or any truthy value; 0/false/empty mean "show it")
  // takes precedence, else config.quietStartup === true. Mirrors getHideStatus.
  function getQuietStartup() {
    const env = process.env.PONYTAIL_QUIET_STARTUP;
    if (env !== undefined) {
      const v = env.trim().toLowerCase();
      return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
    }
    try {
      const config = JSON.parse(fs.readFileSync(getConfigPath(), 'utf8').replace(/^\uFEFF/, ''));
      return config.quietStartup === true;
    } catch (_) {
      return false;
    }
  }
  
  // Hide the status-bar indicator while keeping ponytail active (#324).
  // PONYTAIL_HIDE_STATUS=1 (or any truthy value; 0/false/empty mean "don't hide")
  // takes precedence, else config.hideStatus === true.
  function getHideStatus() {
    const env = process.env.PONYTAIL_HIDE_STATUS;
    if (env !== undefined) {
      const v = env.trim().toLowerCase();
      return v !== '' && v !== '0' && v !== 'false' && v !== 'no';
    }
    try {
      const config = JSON.parse(fs.readFileSync(getConfigPath(), 'utf8').replace(/^\uFEFF/, ''));
      return config.hideStatus === true;
    } catch (_) {
      return false;
    }
  }
  
  function writeDefaultMode(mode) {
    // ponytail: only a runtime level can be a default; review is session-only (#377).
    const normalized = normalizeMode(mode);
    if (!normalized) return null;
  
    const configPath = getConfigPath();
    fs.mkdirSync(path.dirname(configPath), { recursive: true });
    let config = {};
    try {
      config = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\uFEFF/, ''));
      if (!config || typeof config !== 'object' || Array.isArray(config)) config = {};
    } catch (_) {}
    config.defaultMode = normalized;
    fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
    return normalized;
  }
  
  module.exports = {
    DEFAULT_MODE,
    VALID_MODES,
    RUNTIME_MODES,
    getDefaultMode,
    getConfigDir,
    getConfigPath,
    getClaudeDir,
    getHideStatus,
    getQuietStartup,
    isShellSafe,
    normalizeMode,
    normalizeConfigMode,
    normalizePersistedMode,
    isDeactivationCommand,
    writeDefaultMode,
  };
  

• hooks/ponytail-instructions.jsGitHub ↗
  Read the script

  #!/usr/bin/env node
  // Shared Ponytail instruction builder for Claude hooks and Pi extension.
  
  const fs = require('fs');
  const path = require('path');
  const { DEFAULT_MODE, normalizeMode, normalizePersistedMode } = require('./ponytail-config');
  
  const INDEPENDENT_MODES = new Set(['review']);
  const SKILL_PATH = path.join(__dirname, '..', 'skills', 'ponytail', 'SKILL.md');
  
  function filterSkillBodyForMode(body, mode) {
    const effectiveMode = normalizeMode(mode) || DEFAULT_MODE;
    const withoutFrontmatter = String(body || '').replace(/^---[\s\S]*?---\s*/, '');
  
    // Only the intensity table rows and worked examples are mode-specific, and
    // both are keyed by a mode name (lite/full/ultra). A bullet whose label is
    // not a mode — e.g. "No unrequested abstractions: ..." — is a normal rule
    // and must be kept verbatim.
    return withoutFrontmatter
      .split(/\r?\n/)
      .filter((line) => {
        const tableLabel = line.match(/^\|\s*\*\*(.+?)\*\*\s*\|/);
        if (tableLabel) {
          const labelMode = normalizeMode(tableLabel[1].trim());
          if (labelMode) return labelMode === effectiveMode;
        }
  
        // Require a quoted value: every worked example is `- lite: "..."`. Without
        // this, an ordinary rule bullet that happens to start with a mode word
        // (e.g. "- Full: ...") is silently dropped in every other mode — it looks
        // like a worked example but is really prose meant to survive verbatim.
        const exampleLabel = line.match(/^-\s*([^:]+):\s*"/);
        if (exampleLabel) {
          const labelMode = normalizeMode(exampleLabel[1].trim());
          if (labelMode) return labelMode === effectiveMode;
        }
  
        return true;
      })
      .join('\n');
  }
  
  function getFallbackInstructions(mode) {
    return 'PONYTAIL MODE ACTIVE — level: ' + mode + '\n\n' +
      'You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.\n\n' +
      '## Persistence\n\n' +
      'ACTIVE EVERY RESPONSE. No drift back to over-building. Still active if unsure. Off only: "stop ponytail" / "normal mode".\n\n' +
      'Current level: **' + mode + '**. Switch: `/ponytail lite|full|ultra`.\n\n' +
      '## The ladder\n\n' +
      'Before any code, stop at the first rung that holds (the ladder runs after you understand the problem, not instead of it — read the code it touches and trace the real flow first):\n' +
      '1. Does this need to be built at all? (YAGNI)\n' +
      '2. Does it already exist in this codebase? Reuse what is already here, do not re-write it.\n' +
      '3. Does the standard library do this? Use it.\n' +
      '4. Does a native platform feature cover it? Use it.\n' +
      '5. Does an already-installed dependency solve it? Use it.\n' +
      '6. Can this be one line? Make it one line.\n' +
      '7. Only then: write the minimum code that works.\n\n' +
      'Bug fix = root cause, not symptom: grep every caller of the function you touch and fix the shared function once (a smaller diff than one guard per caller); patching only the path the ticket names leaves a sibling caller broken.\n\n' +
      '## Rules\n\n' +
      'No abstractions that were not requested. No avoidable dependencies. No boilerplate nobody asked for. ' +
      'Deletion over addition. Boring over clever. Fewest files possible. ' +
      'Ship the lazy version and question the complex request in the same response — never stall. ' +
      'Between two same-size stdlib options, pick the one correct on edge cases. ' +
      'Mark deliberate simplifications that cut a real corner with a known ceiling, using a `ponytail:` comment that names the ceiling and upgrade path.\n\n' +
      '## Output\n\n' +
      'Code first. Then at most three short lines: what was skipped, when to add it. ' +
      'If the explanation is longer than the code, delete the explanation. ' +
      'Explanation the user explicitly asked for is not debt, give it in full.\n\n' +
      '## When NOT to be lazy\n\n' +
      'Never simplify away: understanding the problem (read it fully and trace the real flow before picking a rung — a small diff you do not understand is just laziness dressed up as efficiency), input validation at trust boundaries, error handling that prevents data loss, ' +
      'security measures, accessibility basics, the calibration real hardware needs (the platform is never the spec ideal), anything the user explicitly asked to keep. ' +
      'Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind (assert-based demo/self-check or one small test file; no frameworks). Trivial one-liners need no test.\n\n' +
      '## Boundaries\n\n' +
      'Ponytail governs what you build, not how you talk. "stop ponytail" or "normal mode": revert. Level persists until changed or session end.';
  }
  
  function getPonytailInstructions(mode) {
    const configuredMode = normalizePersistedMode(mode) || DEFAULT_MODE;
  
    if (INDEPENDENT_MODES.has(configuredMode)) {
      return 'PONYTAIL MODE ACTIVE — level: ' + configuredMode + '. Behavior defined by /ponytail-' + configuredMode + ' skill.';
    }
  
    const effectiveMode = normalizeMode(configuredMode) || DEFAULT_MODE;
  
    try {
      return 'PONYTAIL MODE ACTIVE — level: ' + effectiveMode + '\n\n' +
        filterSkillBodyForMode(fs.readFileSync(SKILL_PATH, 'utf8'), effectiveMode);
    } catch (e) {
      return getFallbackInstructions(effectiveMode);
    }
  }
  
  module.exports = {
    filterSkillBodyForMode,
    getFallbackInstructions,
    getPonytailInstructions,
  };
  

• hooks/ponytail-mode-tracker.jsGitHub ↗
  Read the script

  #!/usr/bin/env node
  // ponytail — UserPromptSubmit hook to track which ponytail mode is active
  // Inspects user input for /ponytail commands and writes mode to flag file
  
  const { getDefaultMode, isDeactivationCommand, writeDefaultMode } = require('./ponytail-config');
  const {
    clearMode,
    cursorRuleNotice,
    cursorRulePath,
    isCursor,
    isQoder,
    readMode,
    setMode,
    writeHookOutput,
  } = require('./ponytail-runtime');
  const { getPonytailInstructions } = require('./ponytail-instructions');
  
  let input = '';
  let done = false;
  
  function finish() {
    if (done) return;
    done = true;
    try {
      // Strip UTF-8 BOM some shells prepend when piping (breaks JSON.parse)
      const data = JSON.parse(input.replace(/^\uFEFF/, ''));
      const prompt = (data.prompt || '').trim().toLowerCase();
  
      // Cursor with the always-on rule in the workspace: no hook can change or
      // switch off a rule, so answer the command with the notice instead of
      // writing a mode the rule would contradict (#817). Ordinary prompts
      // stay silent as usual.
      if (isCursor && (/^[/@$]ponytail/.test(prompt) || isDeactivationCommand(prompt))) {
        const rule = cursorRulePath();
        if (rule) {
          writeHookOutput('UserPromptSubmit', readMode() || 'off', cursorRuleNotice(rule));
          return;
        }
      }
  
      // Match /ponytail commands
      let modeSwitched = false;
      let deactivated = false;
      if (/^[/@$]ponytail/.test(prompt)) {
        const parts = prompt.split(/\s+/);
        const cmd = parts[0].replace(/^[@$]/, '/');
        const arg = parts[1] || '';
  
        let mode = null;
        let isReportOnly = false;
  
        if (cmd === '/ponytail-review' || cmd === '/ponytail:ponytail-review') {
          mode = 'review';
        } else if (cmd === '/ponytail' || cmd === '/ponytail:ponytail') {
          // `/ponytail default <mode>` persists the default to config (survives
          // restarts). Plain switches stay session-scoped ("sticks until session
          // end"), so this is the only path that writes config. review is not a
          // valid default (#377), so only off/lite/full/ultra are accepted.
          if (arg === 'default') {
            const dmode = parts[2];
            if (dmode === 'off' || dmode === 'lite' || dmode === 'full' || dmode === 'ultra') {
              writeDefaultMode(dmode);
              writeHookOutput('UserPromptSubmit', dmode, 'PONYTAIL DEFAULT SET — new sessions start in ' + dmode + '.');
            }
            return; // don't fall through to the session-mode switch
          }
          if (arg === 'lite') mode = 'lite';
          else if (arg === 'full') mode = 'full';
          else if (arg === 'ultra') mode = 'ultra';
          else if (arg === 'off') mode = 'off';
          else if (arg === '') {
            isReportOnly = true;
            mode = readMode() || getDefaultMode();
          } else {
            mode = getDefaultMode();
          }
        }
  
        if (isReportOnly) {
          writeHookOutput(
            'UserPromptSubmit',
            mode,
            'PONYTAIL MODE ACTIVE — level: ' + mode,
          );
        } else if (mode && mode !== 'off') {
          setMode(mode);
          modeSwitched = true;
          // ponytail: Qoder needs the full ruleset every turn, so when a mode
          // switch happens we fold the confirmation into the ruleset output
          // below (one JSON on stdout) instead of emitting two separate writes.
          if (!isQoder) {
            // Cursor has no /ponytail command that would load the skill body
            // for the new level, so the tracker delivers that level's ruleset
            // along with the confirmation (#817).
            const header = 'PONYTAIL MODE CHANGED — level: ' + mode;
            writeHookOutput(
              'UserPromptSubmit',
              mode,
              isCursor ? header + '\n\n' + getPonytailInstructions(mode) : header,
            );
          }
        } else if (mode === 'off') {
          clearMode();
          deactivated = true;
          writeHookOutput('UserPromptSubmit', 'off', 'PONYTAIL MODE OFF');
        }
      }
  
      // Detect deactivation
      if (!modeSwitched && !deactivated && isDeactivationCommand(prompt)) {
        clearMode();
        deactivated = true;
        writeHookOutput('UserPromptSubmit', 'off', 'PONYTAIL MODE OFF');
      }
  
      // Qoder has no SessionStart event, so UserPromptSubmit does double duty:
      // activate the default mode on first prompt (if no flag exists yet), then
      // inject the ruleset on every prompt. Claude Code/Codex do this in
      // SessionStart via ponytail-activate.js; Qoder can't, so we do it here.
      // Skip when deactivated — user just turned ponytail off.
      if (isQoder && !deactivated) {
        let currentMode = readMode();
        if (!currentMode) {
          // First prompt in session — initialize from config/env default
          currentMode = getDefaultMode();
          if (currentMode !== 'off') {
            try { setMode(currentMode); } catch (e) {}
          }
        }
        if (currentMode && currentMode !== 'off') {
          // ponytail: one JSON per invocation — mode-switch confirmation is
          // folded into the ruleset header so Qoder gets both in one write.
          const header = modeSwitched
            ? 'PONYTAIL MODE CHANGED — level: ' + currentMode + '\n\n'
            : '';
          writeHookOutput('UserPromptSubmit', currentMode, header + getPonytailInstructions(currentMode));
        }
      }
    } catch (e) {
      // Silent fail
    }
  }
  
  process.stdin.on('data', chunk => { input += chunk; });
  process.stdin.on('end', finish);
  
  // Never hang the session. On Windows, Claude Code runs this hook through a
  // PowerShell `if {}` wrapper that can swallow the piped prompt JSON, so stdin
  // 'end' never fires and the hook blocks forever — freezing the session (#443).
  // On error, or after a short fallback, process whatever arrived (recovering the
  // mode if data came without EOF) and exit. unref() keeps the timer from adding
  // latency to the normal path, where 'end' fires first. Mirrors the best-effort,
  // never-block cont

• hooks/ponytail-runtime.jsGitHub ↗
  Read the script

  const fs = require('fs');
  const path = require('path');
  const os = require('os');
  const { getClaudeDir, getConfigDir } = require('./ponytail-config');
  
  const STATE_FILE = '.ponytail-active';
  
  // ponytail: VS Code Copilot never sets COPILOT_PLUGIN_DATA — it only injects
  // CLAUDE_PLUGIN_ROOT, pointed at an install path under .vscode/agent-plugins/
  // (#528). Without this fallback isCopilot was false, so ponytail assumed
  // native Claude Code and emitted the statusline nudge, which VS Code Copilot
  // doesn't read.
  function isVsCodeCopilotRoot(pluginRoot) {
    if (!pluginRoot) return false;
    return pluginRoot.split(/[\\/]+/).includes('agent-plugins') &&
      pluginRoot.toLowerCase().includes('.vscode');
  }
  
  const isCopilot = Boolean(process.env.COPILOT_PLUGIN_DATA) ||
    isVsCodeCopilotRoot(process.env.CLAUDE_PLUGIN_ROOT);
  const isCodex = !isCopilot && Boolean(process.env.PLUGIN_DATA);
  const isQoder = !isCopilot && !isCodex && Boolean(process.env.QODER_SESSION_ID);
  // Cursor (#817): CURSOR_VERSION is set only in the environment Cursor builds
  // for hook processes (Cursor 3.20.17 assigns it in exactly one place, the hook
  // env builder), so it never leaks into a Claude Code session running inside
  // Cursor's terminal. Cursor also sets it when it runs a Claude-format plugin's
  // hooks next to CLAUDE_PLUGIN_ROOT, and it needs Cursor-shaped JSON either
  // way, so this check comes after the hosts with their own data dirs.
  const isCursor = !isCopilot && !isCodex && !isQoder && Boolean(process.env.CURSOR_VERSION);
  
  let stateDir = getClaudeDir();
  if (isCodex) stateDir = process.env.PLUGIN_DATA;
  // COPILOT_PLUGIN_DATA is unset under VS Code Copilot, so fall back to
  // getClaudeDir() rather than building a path from undefined.
  if (isCopilot) stateDir = process.env.COPILOT_PLUGIN_DATA || getClaudeDir();
  if (isQoder) stateDir = path.join(os.homedir(), '.qoder');
  if (isCursor) stateDir = path.join(os.homedir(), '.cursor');
  
  const statePath = path.join(stateDir, STATE_FILE);
  
  function setMode(mode) {
    fs.mkdirSync(path.dirname(statePath), { recursive: true });
    fs.writeFileSync(statePath, mode);
  }
  
  function clearMode() {
    try { fs.unlinkSync(statePath); } catch (e) {}
  }
  
  // Live mode written by activate/mode-tracker. Absent flag = ponytail off.
  function readMode() {
    try {
      return fs.readFileSync(statePath, 'utf8').trim() || null;
    } catch (e) {
      return null;
    }
  }
  
  // Cursor's always-on project rule (.cursor/rules/ponytail.mdc) already puts the
  // ruleset in front of every prompt and no hook can switch a rule off, so while
  // it is in the workspace the hooks step back instead of injecting a second,
  // possibly contradicting, copy (#817). Cursor hands every hook the workspace
  // root as CURSOR_PROJECT_DIR; project hooks also run from that directory.
  // ponytail: first workspace root only, a rule in a secondary folder of a
  // multi-root workspace goes undetected.
  function cursorRulePath() {
    const root = process.env.CURSOR_PROJECT_DIR || process.cwd();
    const rule = path.join(root, '.cursor', 'rules', 'ponytail.mdc');
    return fs.existsSync(rule) ? rule : null;
  }
  
  function cursorRuleNotice(rule) {
    return 'PONYTAIL: the always-on Cursor rule ' + rule + ' is active in this workspace and ' +
      'already carries the ponytail ruleset, so the ponytail hooks injected nothing further. ' +
      'Mode switching (/ponytail lite|full|ultra|off, "stop ponytail") is unavailable while ' +
      'that rule exists. When the user tries to switch or turn off ponytail, tell them to ' +
      'delete that rule so hooks.json can manage the level.';
  }
  
  function writeHookOutput(event, mode, context = '') {
    if (isCopilot) {
      // Copilot reads additionalContext on SessionStart; ignores output elsewhere.
      process.stdout.write(JSON.stringify(
        event === 'SessionStart' && context ? { additionalContext: context } : {}));
      return;
    }
    if (isCodex) {
      const output = { systemMessage: `PONYTAIL:${mode.toUpperCase()}` };
      if (context) {
        output.hookSpecificOutput = {
          hookEventName: event,
          additionalContext: context,
        };
      }
      process.stdout.write(JSON.stringify(output));
      return;
    }
    if (isQoder) {
      // Qoder: hookSpecificOutput JSON, same shape as Codex minus systemMessage.
      // UserPromptSubmit additionalContext is injected into the Agent's conversation.
      const output = {};
      if (context) {
        output.hookSpecificOutput = {
          hookEventName: event,
          additionalContext: context,
        };
      }
      process.stdout.write(JSON.stringify(output));
      return;
    }
    if (isCursor) {
      // Cursor parses stdout as JSON and treats empty stdout as "nothing to
      // say"; raw text would be logged as a parse error. sessionStart takes
      // additional_context into the conversation's system context;
      // beforeSubmitPrompt needs continue:true and, in Cursor 3.20.17, injects
      // additional_context into that turn (docs/cursor-hooks.md).
      if (!context) return;
      const output = { additional_context: context };
      if (event === 'UserPromptSubmit') output.continue = true;
      process.stdout.write(JSON.stringify(output));
      return;
    }
    // Native Claude: SessionStart accepts raw stdout, but SubagentStart needs the
    // hookSpecificOutput JSON form or the context is dropped.
    if (event === 'SubagentStart') {
      process.stdout.write(JSON.stringify(
        { hookSpecificOutput: { hookEventName: event, additionalContext: context } }));
      return;
    }
    process.stdout.write(context);
  }
  
  module.exports = {
    clearMode,
    cursorRuleNotice,
    cursorRulePath,
    isCodex,
    isCopilot,
    isCursor,
    isQoder,
    readMode,
    setMode,
    writeHookOutput,
  };
  

• hooks/ponytail-statusline.ps1GitHub ↗
  Read the script

  # CLAUDE_CONFIG_DIR overrides ~/.claude, matching where the hooks write the flag (issue #34)
  $ClaudeDir = if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $HOME ".claude" }
  $Flag = Join-Path $ClaudeDir ".ponytail-active"
  if (-not (Test-Path $Flag)) {
      exit 0
  }
  
  $Mode = ""
  try {
      $Mode = (Get-Content $Flag -ErrorAction Stop | Select-Object -First 1).Trim()
  } catch {
      exit 0
  }
  
  $Esc = [char]27
  # ultra is the high-intensity mode; flag it amber so it stands out from the
  # default green. The level is still in the text, so color is a redundant cue.
  $Color = if ($Mode -eq "ultra") { "173" } else { "108" }
  if ([string]::IsNullOrEmpty($Mode) -or $Mode -eq "full") {
      [Console]::Write("${Esc}[38;5;${Color}m[PONYTAIL]${Esc}[0m")
  } else {
      $Suffix = $Mode.ToUpperInvariant()
      [Console]::Write("${Esc}[38;5;${Color}m[PONYTAIL:$Suffix]${Esc}[0m")
  }
  

• hooks/ponytail-statusline.shGitHub ↗
• hooks/ponytail-subagent.jsGitHub ↗

All 8 scripts are listed above. The source is inlined for 6 of them, starting with whatever hooks.json actually runs. See all of them in the repo.

Read the script before you install anything that runs on your machine. This is the one part of a plugin that acts without being asked.