dmux 3.0.2 → 3.1.1

package/dist/utils/hooks.js

@@ -0,0 +1,216 @@
+/**
+ * Hooks System
+ *
+ * Executes user-defined scripts at key lifecycle events.
+ * Hook scripts are stored in .dmux/hooks/ and receive context via environment variables.
+ */
+import { execSync, spawn } from 'child_process';
+import { existsSync, accessSync, constants, mkdirSync, writeFileSync } from 'fs';
+import path from 'path';
+import os from 'os';
+import { HOOKS_DOCUMENTATION, HOOKS_README, EXAMPLE_HOOKS } from './hooksDocs.js';
+/**
+ * Find a hook script with priority resolution:
+ * 1. .dmux-hooks/ (version controlled, team hooks)
+ * 2. .dmux/hooks/ (gitignored, local overrides)
+ * 3. ~/.dmux/hooks/ (global user hooks)
+ */
+export function findHook(projectRoot, hookName) {
+    const searchPaths = [
+        path.join(projectRoot, '.dmux-hooks', hookName), // Team hooks (VC)
+        path.join(projectRoot, '.dmux', 'hooks', hookName), // Local override
+        path.join(os.homedir(), '.dmux', 'hooks', hookName), // Global hooks
+    ];
+    for (const hookPath of searchPaths) {
+        if (existsSync(hookPath)) {
+            try {
+                // Check if file is executable
+                accessSync(hookPath, constants.X_OK);
+                return hookPath;
+            }
+            catch {
+                console.error(`[Hooks] Warning: Hook "${hookName}" exists at ${hookPath} but is not executable. Run: chmod +x ${hookPath}`);
+                // Continue searching other locations
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Build environment variables for a hook
+ */
+export async function buildHookEnvironment(projectRoot, pane, extraData) {
+    const env = {
+        DMUX_ROOT: projectRoot,
+        ...process.env, // Inherit parent environment
+    };
+    // Add server port if available
+    const { StateManager } = await import('../shared/StateManager.js');
+    const state = StateManager.getInstance().getState();
+    if (state.serverPort) {
+        env.DMUX_SERVER_PORT = String(state.serverPort);
+    }
+    // Add pane-specific data
+    if (pane) {
+        env.DMUX_PANE_ID = pane.id;
+        env.DMUX_SLUG = pane.slug;
+        env.DMUX_PROMPT = pane.prompt;
+        env.DMUX_AGENT = pane.agent || 'unknown';
+        env.DMUX_TMUX_PANE_ID = pane.paneId;
+        if (pane.worktreePath) {
+            env.DMUX_WORKTREE_PATH = pane.worktreePath;
+            env.DMUX_BRANCH = pane.slug; // Branch name matches slug
+        }
+    }
+    // Add any extra data
+    if (extraData) {
+        Object.assign(env, extraData);
+    }
+    return env;
+}
+/**
+ * Execute a hook script asynchronously
+ *
+ * Hooks run in the background and don't block dmux operations.
+ * Errors are logged but don't crash the application.
+ */
+export async function triggerHook(hookName, projectRoot, pane, extraData) {
+    // Initialize hooks directory on first use (lazy init)
+    initializeHooksDirectory(projectRoot);
+    const hookPath = findHook(projectRoot, hookName);
+    if (!hookPath) {
+        // No hook script found, that's fine
+        return;
+    }
+    // Build environment
+    const env = await buildHookEnvironment(projectRoot, pane, extraData);
+    // Log hook execution
+    console.error(`[Hooks] Executing ${hookName} hook: ${hookPath}`);
+    try {
+        // Spawn hook process in background
+        const child = spawn(hookPath, [], {
+            env: env,
+            cwd: projectRoot,
+            detached: true,
+            stdio: 'ignore', // Don't capture output by default
+        });
+        // Detach so the hook can run independently
+        child.unref();
+        // Optional: Log when hook completes (but don't wait for it)
+        child.on('exit', (code) => {
+            if (code === 0) {
+                console.error(`[Hooks] ${hookName} completed successfully`);
+            }
+            else if (code !== null) {
+                console.error(`[Hooks] ${hookName} exited with code ${code}`);
+            }
+        });
+        child.on('error', (error) => {
+            console.error(`[Hooks] ${hookName} failed to start: ${error.message}`);
+        });
+    }
+    catch (error) {
+        console.error(`[Hooks] Failed to execute ${hookName}: ${error}`);
+    }
+}
+/**
+ * Execute a hook synchronously (blocking)
+ *
+ * Use sparingly - only for hooks that MUST complete before proceeding.
+ * Most hooks should use triggerHook() instead.
+ */
+export async function triggerHookSync(hookName, projectRoot, pane, extraData, timeoutMs = 30000) {
+    const hookPath = findHook(projectRoot, hookName);
+    if (!hookPath) {
+        return { success: true }; // No hook = success
+    }
+    const env = await buildHookEnvironment(projectRoot, pane, extraData);
+    console.error(`[Hooks] Executing ${hookName} hook (sync): ${hookPath}`);
+    try {
+        const output = execSync(hookPath, {
+            env: env,
+            cwd: projectRoot,
+            encoding: 'utf-8',
+            timeout: timeoutMs,
+            stdio: 'pipe',
+        });
+        console.error(`[Hooks] ${hookName} completed successfully`);
+        return { success: true, output };
+    }
+    catch (error) {
+        const errorMsg = error.message || String(error);
+        console.error(`[Hooks] ${hookName} failed: ${errorMsg}`);
+        return {
+            success: false,
+            error: errorMsg,
+            output: error.stdout?.toString() || '',
+        };
+    }
+}
+/**
+ * Check if a hook exists for a given hook type
+ */
+export function hasHook(projectRoot, hookName) {
+    return findHook(projectRoot, hookName) !== null;
+}
+/**
+ * List all available hooks in the project
+ */
+export function listAvailableHooks(projectRoot) {
+    const allHooks = [
+        'before_pane_create',
+        'pane_created',
+        'worktree_created',
+        'before_pane_close',
+        'pane_closed',
+        'before_worktree_remove',
+        'worktree_removed',
+        'pre_merge',
+        'post_merge',
+        'run_test',
+        'run_dev',
+    ];
+    return allHooks.filter((hook) => hasHook(projectRoot, hook));
+}
+/**
+ * Initialize .dmux-hooks/ directory with documentation and examples
+ * This gets called the first time hooks are accessed or when user explicitly initializes
+ */
+export function initializeHooksDirectory(projectRoot) {
+    const hooksDir = path.join(projectRoot, '.dmux-hooks');
+    // Skip if already initialized
+    if (existsSync(path.join(hooksDir, 'AGENTS.md'))) {
+        return;
+    }
+    console.error('[Hooks] Initializing .dmux-hooks/ directory...');
+    // Create main hooks directory
+    if (!existsSync(hooksDir)) {
+        mkdirSync(hooksDir, { recursive: true });
+    }
+    // Write AGENTS.md (complete reference)
+    writeFileSync(path.join(hooksDir, 'AGENTS.md'), HOOKS_DOCUMENTATION, 'utf-8');
+    // Write CLAUDE.md (identical to AGENTS.md, just different filename for Claude Code)
+    writeFileSync(path.join(hooksDir, 'CLAUDE.md'), HOOKS_DOCUMENTATION, 'utf-8');
+    // Write README.md
+    writeFileSync(path.join(hooksDir, 'README.md'), HOOKS_README, 'utf-8');
+    // Create examples directory
+    const examplesDir = path.join(hooksDir, 'examples');
+    if (!existsSync(examplesDir)) {
+        mkdirSync(examplesDir, { recursive: true });
+    }
+    // Write example hooks
+    for (const [filename, content] of Object.entries(EXAMPLE_HOOKS)) {
+        const examplePath = path.join(examplesDir, filename);
+        writeFileSync(examplePath, content, 'utf-8');
+        // Make examples executable
+        try {
+            execSync(`chmod +x "${examplePath}"`, { stdio: 'pipe' });
+        }
+        catch {
+            // Ignore chmod errors (Windows, etc.)
+        }
+    }
+    console.error('[Hooks] ✅ Initialized .dmux-hooks/ with documentation and examples');
+    console.error('[Hooks] 📝 Read AGENTS.md or CLAUDE.md to get started');
+}
+//# sourceMappingURL=hooks.js.map

package/dist/utils/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../../src/utils/hooks.ts"],"names":[],"mappings":"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"}

package/dist/utils/hooksDocs.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Embedded Hooks Documentation
+ *
+ * This file contains all documentation that gets written to .dmux-hooks/
+ * when the directory is initialized. The AGENTS_MD content is auto-generated
+ * and imported from generated-agents-doc.ts
+ */
+/**
+ * Main documentation - gets written as both AGENTS.md and CLAUDE.md
+ * Different agents look for different filenames, but content is identical
+ */
+export declare const HOOKS_DOCUMENTATION = "# dmux Hooks System - Agent Reference\n\n**Auto-generated documentation for AI agents**\n\nThis document contains everything an AI agent needs to create, modify, and understand dmux hooks. It is automatically generated from the dmux source code and embedded in the binary.\n\n## What You're Working On\n\nYou are editing hooks for **dmux**, a tmux pane manager that creates AI-powered development workflows. Each pane runs in its own git worktree with an AI agent (Claude Code or opencode).\n\n## Your Goal\n\nCreate executable bash scripts in `.dmux-hooks/` that run automatically at key lifecycle events.\n\n## Quick Start\n\n1. **Create a hook file**: `touch .dmux-hooks/worktree_created`\n2. **Make it executable**: `chmod +x .dmux-hooks/worktree_created`\n3. **Add shebang**: Start with `#!/bin/bash`\n4. **Use environment variables**: Access `$DMUX_ROOT`, `$DMUX_WORKTREE_PATH`, etc.\n5. **Test it**: Set env vars manually and run the script\n\n## Hook Execution Model\n\n- **Non-blocking**: Hooks run in background (detached processes)\n- **Silent failures**: Hook errors are logged but don't stop dmux\n- **Environment-based**: All context passed via environment variables\n- **Version controlled**: Hooks in `.dmux-hooks/` are shared with team\n- **Priority resolution**: `.dmux-hooks/` \u2192 `.dmux/hooks/` \u2192 `~/.dmux/hooks/`\n\n## Available Hooks\n\n### Pane Lifecycle Hooks\n\n| Hook | When | Common Use Cases |\n|------|------|------------------|\n| `before_pane_create` | Before pane creation | Validation, notifications, pre-flight checks |\n| `pane_created` | After pane, before worktree | Configure tmux settings, prepare environment |\n| `worktree_created` | After full setup | Install deps, copy configs, setup git |\n| `before_pane_close` | Before closing | Save state, backup uncommitted work |\n| `pane_closed` | After closed | Cleanup resources, analytics, notifications |\n\n### Worktree Lifecycle Hooks\n\n| Hook | When | Common Use Cases |\n|------|------|------------------|\n| `before_worktree_remove` | Before worktree removal | Archive worktree, save artifacts |\n| `worktree_removed` | After worktree removed | Cleanup external references |\n\n### Merge Lifecycle Hooks\n\n| Hook | When | Common Use Cases |\n|------|------|------------------|\n| `pre_merge` | Before merge operation | Run final tests, create backups |\n| `post_merge` | After successful merge | Deploy, close issues, notify team |\n\n### Interactive Hooks (with HTTP callbacks)\n\n| Hook | When | Common Use Cases |\n|------|------|------------------|\n| `run_test` | When tests triggered | Run test suite, report status via HTTP |\n| `run_dev` | When dev server triggered | Start dev server, create tunnel, report URL |\n\n\n## Environment Variables\n\n### Always Available\n```bash\nDMUX_ROOT=\"/path/to/project\"           # Project root directory\nDMUX_SERVER_PORT=\"3142\"                # HTTP server port\n```\n\n### Pane Context (most hooks)\n```bash\nDMUX_PANE_ID=\"dmux-1234567890\"         # dmux pane identifier\nDMUX_SLUG=\"fix-auth-bug\"               # Branch/worktree name\nDMUX_PROMPT=\"Fix authentication bug\"   # User's prompt\nDMUX_AGENT=\"claude\"                    # Agent type (claude|opencode)\nDMUX_TMUX_PANE_ID=\"%38\"                # tmux pane ID\n```\n\n### Worktree Context\n```bash\nDMUX_WORKTREE_PATH=\"/path/.dmux/worktrees/fix-auth-bug\"\nDMUX_BRANCH=\"fix-auth-bug\"             # Same as slug\n```\n\n### Merge Context\n```bash\nDMUX_TARGET_BRANCH=\"main\"              # Branch being merged into\n```\n\n## HTTP Callback API\n\nInteractive hooks (`run_test` and `run_dev`) can update dmux UI via HTTP.\n\n### Update Test Status\n```bash\ncurl -X PUT \"http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/test\"   -H \"Content-Type: application/json\"   -d '{\"status\": \"running\", \"output\": \"optional test output\"}'\n\n# Status values: \"running\" | \"passed\" | \"failed\"\n```\n\n### Update Dev Server\n```bash\ncurl -X PUT \"http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/dev\"   -H \"Content-Type: application/json\"   -d '{\"status\": \"running\", \"url\": \"http://localhost:3000\"}'\n\n# Status values: \"running\" | \"stopped\"\n# url: Can be localhost or tunnel URL (ngrok, cloudflared, etc.)\n```\n\n## Common Patterns\n\n### Pattern 1: Install Dependencies\n```bash\n#!/bin/bash\n# .dmux-hooks/worktree_created\n\ncd \"$DMUX_WORKTREE_PATH\"\n\nif [ -f \"pnpm-lock.yaml\" ]; then\n  pnpm install --prefer-offline &\nelif [ -f \"package-lock.json\" ]; then\n  npm install &\nelif [ -f \"yarn.lock\" ]; then\n  yarn install &\nelif [ -f \"Gemfile\" ]; then\n  bundle install &\nelif [ -f \"requirements.txt\" ]; then\n  pip install -r requirements.txt &\nelif [ -f \"Cargo.toml\" ]; then\n  cargo build &\nfi\n```\n\n### Pattern 2: Copy Configuration\n```bash\n#!/bin/bash\n# .dmux-hooks/worktree_created\n\n# Copy environment file\nif [ -f \"$DMUX_ROOT/.env.local\" ]; then\n  cp \"$DMUX_ROOT/.env.local\" \"$DMUX_WORKTREE_PATH/.env.local\"\nfi\n\n# Copy other config files\nfor file in .env.development .npmrc .yarnrc; do\n  if [ -f \"$DMUX_ROOT/$file\" ]; then\n    cp \"$DMUX_ROOT/$file\" \"$DMUX_WORKTREE_PATH/$file\"\n  fi\ndone\n```\n\n### Pattern 3: Run Tests with Status Updates\n```bash\n#!/bin/bash\n# .dmux-hooks/run_test\n\nset -e\ncd \"$DMUX_WORKTREE_PATH\"\nAPI=\"http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/test\"\n\n# Update: starting\ncurl -s -X PUT \"$API\" -H \"Content-Type: application/json\"   -d '{\"status\": \"running\"}' > /dev/null\n\n# Run tests and capture output\nOUTPUT_FILE=\"/tmp/dmux-test-$DMUX_PANE_ID.txt\"\nif pnpm test > \"$OUTPUT_FILE\" 2>&1; then\n  STATUS=\"passed\"\nelse\n  STATUS=\"failed\"\nfi\n\n# Get output (truncate if too long)\nOUTPUT=$(head -c 5000 \"$OUTPUT_FILE\")\n\n# Update: complete\ncurl -s -X PUT \"$API\" -H \"Content-Type: application/json\"   -d \"$(jq -n --arg status \"$STATUS\" --arg output \"$OUTPUT\"     '{status: $status, output: $output}')\" > /dev/null\n\nrm -f \"$OUTPUT_FILE\"\n```\n\n### Pattern 4: Dev Server with Tunnel\n```bash\n#!/bin/bash\n# .dmux-hooks/run_dev\n\nset -e\ncd \"$DMUX_WORKTREE_PATH\"\nAPI=\"http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/dev\"\n\n# Start dev server in background\nLOG_FILE=\"/tmp/dmux-dev-$DMUX_PANE_ID.log\"\npnpm dev > \"$LOG_FILE\" 2>&1 &\nDEV_PID=$!\n\n# Wait for server to start\nsleep 5\n\n# Detect port from logs\nPORT=$(grep -oP 'localhost:Kd+' \"$LOG_FILE\" | head -1)\n[ -z \"$PORT\" ] && PORT=3000\n\n# Optional: Create tunnel with cloudflared\nif command -v cloudflared &> /dev/null; then\n  TUNNEL=$(cloudflared tunnel --url \"http://localhost:$PORT\" 2>&1 |     grep -oP 'https://[a-z0-9-]+.trycloudflare.com' | head -1)\n  URL=\"${TUNNEL:-http://localhost:$PORT}\"\nelse\n  URL=\"http://localhost:$PORT\"\nfi\n\n# Report status\ncurl -s -X PUT \"$API\" -H \"Content-Type: application/json\"   -d \"{\"status\": \"running\", \"url\": \"$URL\"}\" > /dev/null\n\necho \"[Hook] Dev server running at $URL (PID: $DEV_PID)\"\n```\n\n### Pattern 5: Post-Merge Deployment\n```bash\n#!/bin/bash\n# .dmux-hooks/post_merge\n\nset -e\ncd \"$DMUX_ROOT\"\n\n# Only deploy from main/master\nif [ \"$DMUX_TARGET_BRANCH\" != \"main\" ] && [ \"$DMUX_TARGET_BRANCH\" != \"master\" ]; then\n  exit 0\nfi\n\n# Push to remote\ngit push origin \"$DMUX_TARGET_BRANCH\"\n\n# Trigger deployment (example: Vercel)\nif [ -n \"$VERCEL_TOKEN\" ]; then\n  curl -s -X POST \"https://api.vercel.com/v1/deployments\"     -H \"Authorization: Bearer $VERCEL_TOKEN\"     -H \"Content-Type: application/json\"     -d '{\"name\": \"my-project\"}' > /dev/null\nfi\n\n# Close GitHub issue if prompt contains #123\nISSUE=$(echo \"$DMUX_PROMPT\" | grep -oP '#Kd+' | head -1)\nif [ -n \"$ISSUE\" ] && command -v gh &> /dev/null; then\n  gh issue close \"$ISSUE\"     -c \"Resolved in $DMUX_SLUG, merged to $DMUX_TARGET_BRANCH\"     2>/dev/null || true\nfi\n```\n\n## Best Practices\n\n1. **Always start with shebang**: `#!/bin/bash`\n2. **Set error handling**: `set -e` (exit on error)\n3. **Make executable**: `chmod +x .dmux-hooks/hook_name`\n4. **Background long operations**: Append `&` to avoid blocking\n5. **Check for required tools**: `command -v tool &> /dev/null`\n6. **Log for debugging**: `echo \"[Hook] message\" >> \"$DMUX_ROOT/.dmux/hooks.log\"`\n7. **Handle missing vars gracefully**: `[ -z \"$VAR\" ] && exit 0`\n8. **Use silent curl**: `curl -s` to avoid noise in logs\n9. **Clean up temp files**: Remove files in `/tmp/`\n10. **Test before committing**: Run hooks manually with mock env vars\n\n## Testing Hooks\n\n### Manual Testing\n```bash\n# 1. Set environment variables\nexport DMUX_ROOT=\"$(pwd)\"\nexport DMUX_PANE_ID=\"test-pane\"\nexport DMUX_SLUG=\"test-branch\"\nexport DMUX_WORKTREE_PATH=\"$(pwd)\"\nexport DMUX_SERVER_PORT=\"3142\"\nexport DMUX_AGENT=\"claude\"\nexport DMUX_PROMPT=\"Test prompt\"\n\n# 2. Run hook directly\n./.dmux-hooks/worktree_created\n\n# 3. Check exit code\necho $?  # Should be 0 for success\n```\n\n### Syntax Check\n```bash\n# Check for syntax errors without running\nbash -n ./.dmux-hooks/worktree_created\n```\n\n### Shellcheck (if available)\n```bash\nshellcheck ./.dmux-hooks/worktree_created\n```\n\n## Project Context Analysis\n\nBefore creating hooks, analyze these files in the project:\n\n### Package Manager Detection\n```bash\n# Check which package manager is used\nif [ -f \"pnpm-lock.yaml\" ]; then\n  # Use: pnpm install, pnpm test, pnpm dev\nelif [ -f \"package-lock.json\" ]; then\n  # Use: npm install, npm test, npm run dev\nelif [ -f \"yarn.lock\" ]; then\n  # Use: yarn install, yarn test, yarn dev\nfi\n```\n\n### Test Command Discovery\n```bash\n# Read package.json to find test command\ncat package.json | grep '\"test\"'\n# Or with jq:\njq -r '.scripts.test' package.json\n```\n\n### Dev Command Discovery\n```bash\n# Read package.json to find dev command\ncat package.json | grep '\"dev\"'\n# Or with jq:\njq -r '.scripts.dev' package.json\n```\n\n### Environment Variables\n```bash\n# Check for .env files to copy\nls -la | grep '.env'\n```\n\n### Build System\n```bash\n# Detect build system\nif [ -f \"vite.config.ts\" ]; then\n  # Vite project\nelif [ -f \"next.config.js\" ]; then\n  # Next.js project\nelif [ -f \"nuxt.config.ts\" ]; then\n  # Nuxt project\nfi\n```\n\n## Common Mistakes to Avoid\n\n\u274C **Blocking operations**: `sleep 60` (blocks dmux)\n\u2705 **Background long tasks**: `slow_operation &`\n\n\u274C **Hardcoded paths**: `/Users/me/project`\n\u2705 **Use variables**: `\"$DMUX_ROOT\"`\n\n\u274C **Assuming tools exist**: `pnpm install`\n\u2705 **Check first**: `command -v pnpm && pnpm install`\n\n\u274C **No error handling**: Script fails silently\n\u2705 **Set error mode**: `set -e` or check exit codes\n\n\u274C **Forgetting executable bit**: Hook won't run\n\u2705 **Make executable**: `chmod +x`\n\n\u274C **Noisy output**: Clutters dmux logs\n\u2705 **Silent operations**: `curl -s`, `> /dev/null 2>&1`\n\n\u274C **Not testing**: Deploy and hope\n\u2705 **Test manually**: Run with mock env vars first\n\n## Debugging\n\nIf a hook isn't working:\n\n1. **Check if file exists**: `ls -la .dmux-hooks/`\n2. **Check permissions**: Should show `x` in `rwxr-xr-x`\n3. **Check syntax**: `bash -n .dmux-hooks/hook_name`\n4. **Test manually**: Set env vars and run\n5. **Check logs**: dmux logs to stderr with `[Hooks]` prefix\n6. **Simplify**: Remove complex parts, test basic version\n7. **Check tool availability**: `command -v required_tool`\n\n### Debug Mode\n```bash\n#!/bin/bash\n# Add to top of hook for debugging\nset -x  # Print each command before executing\nset -e  # Exit on error\n\n# Your hook logic here\n```\n\n## Summary Checklist\n\nWhen creating a new hook:\n\n- [ ] Create file in `.dmux-hooks/`\n- [ ] Add shebang: `#!/bin/bash`\n- [ ] Make executable: `chmod +x`\n- [ ] Add `set -e` for error handling\n- [ ] Use environment variables (never hardcode paths)\n- [ ] Background long operations with `&`\n- [ ] Check for required tools before using\n- [ ] Test manually with mock env vars\n- [ ] Add comments explaining what it does\n- [ ] Commit to version control\n\n## Getting Help\n\n- **Full documentation**: See `HOOKS.md` in project root\n- **Claude-specific tips**: See `CLAUDE.md` in `.dmux-hooks/`\n- **Examples**: Check `.dmux-hooks/examples/` directory\n- **dmux API**: See `API.md` for REST endpoints\n\n---\n\n*This documentation was auto-generated from dmux source code.*\n*Version: 2025-10-13*\n";
+/**
+ * README for the .dmux-hooks/ directory
+ */
+export declare const HOOKS_README = "# dmux Hooks\n\nThis directory contains hooks that run automatically at key lifecycle events in dmux.\n\n## Quick Start\n\n1. **Read the documentation**:\n   - `AGENTS.md` - Complete reference (for any AI agent)\n   - `CLAUDE.md` - Same content (Claude Code looks for this filename)\n\n2. **Check examples**:\n   - `examples/` directory contains starter templates\n\n3. **Create a hook**:\n   ```bash\n   touch worktree_created\n   chmod +x worktree_created\n   nano worktree_created\n   ```\n\n4. **Test it**:\n   ```bash\n   export DMUX_ROOT=\"$(pwd)\"\n   export DMUX_WORKTREE_PATH=\"$(pwd)\"\n   ./worktree_created\n   ```\n\n## Available Hooks\n\n- `before_pane_create` - Before pane creation\n- `pane_created` - After pane created\n- `worktree_created` - After worktree setup\n- `before_pane_close` - Before closing\n- `pane_closed` - After closed\n- `before_worktree_remove` - Before worktree removal\n- `worktree_removed` - After worktree removed\n- `pre_merge` - Before merge\n- `post_merge` - After merge\n- `run_test` - When running tests\n- `run_dev` - When starting dev server\n\n## Documentation\n\nSee `AGENTS.md` or `CLAUDE.md` for complete documentation including:\n- Environment variables\n- HTTP callback API\n- Common patterns\n- Best practices\n- Testing strategies\n\n## Note\n\nThis directory is **version controlled**. Hooks you create here will be shared with your team.\n";
+/**
+ * Example: worktree_created hook
+ */
+export declare const EXAMPLE_WORKTREE_CREATED = "#!/bin/bash\n# Example: worktree_created hook\n#\n# This hook runs after a new worktree is created and the agent is launched.\n# Use it to set up the worktree environment (install deps, copy configs, etc.)\n\nset -e  # Exit on error\n\necho \"[Hook] Setting up worktree: $DMUX_SLUG\"\n\ncd \"$DMUX_WORKTREE_PATH\"\n\n# Install dependencies in background (don't block dmux)\nif [ -f \"pnpm-lock.yaml\" ]; then\n  echo \"[Hook] Installing dependencies with pnpm...\"\n  pnpm install --prefer-offline &\nelif [ -f \"package-lock.json\" ]; then\n  echo \"[Hook] Installing dependencies with npm...\"\n  npm install &\nelif [ -f \"yarn.lock\" ]; then\n  echo \"[Hook] Installing dependencies with yarn...\"\n  yarn install &\nfi\n\n# Copy environment file if it exists\nif [ -f \"$DMUX_ROOT/.env.local\" ]; then\n  echo \"[Hook] Copying .env.local\"\n  cp \"$DMUX_ROOT/.env.local\" \"$DMUX_WORKTREE_PATH/.env.local\"\nfi\n\n# Set custom git config for this worktree\necho \"[Hook] Configuring git\"\ngit config user.name \"dmux-agent/$DMUX_SLUG\"\ngit config user.email \"agent@dmux.local\"\n\n# Create a log entry\necho \"[$(date)] Created worktree: $DMUX_SLUG | Agent: $DMUX_AGENT | Prompt: $DMUX_PROMPT\" \\\n  >> \"$DMUX_ROOT/.dmux/worktree_history.log\"\n\necho \"[Hook] Worktree setup complete!\"\n";
+/**
+ * Example: run_dev hook
+ */
+export declare const EXAMPLE_RUN_DEV = "#!/bin/bash\n# Example: run_dev hook\n#\n# This hook starts a dev server and optionally creates a tunnel for sharing.\n# It reports the server URL back to dmux via the HTTP API.\n\nset -e\n\necho \"[Hook] Starting dev server for $DMUX_SLUG\"\n\ncd \"$DMUX_WORKTREE_PATH\"\nAPI_URL=\"http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/dev\"\n\n# Update status: starting\ncurl -s -X PUT \"$API_URL\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\": \"running\"}' > /dev/null\n\n# Start dev server in background\n# Adjust the command for your project (pnpm dev, npm run dev, vite, etc.)\nLOG_FILE=\"/tmp/dmux-dev-$DMUX_PANE_ID.log\"\npnpm dev > \"$LOG_FILE\" 2>&1 &\nDEV_PID=$!\n\n# Wait for server to be ready\necho \"[Hook] Waiting for dev server to start...\"\nsleep 5\n\n# Detect port from log output\n# Adjust the grep pattern for your dev server's output format\nPORT=$(grep -oP '(?<=localhost:)\\d+' \"$LOG_FILE\" | head -1)\n\nif [ -z \"$PORT\" ]; then\n  echo \"[Hook] Warning: Could not detect port from logs, using default 3000\"\n  PORT=3000\nfi\n\nLOCAL_URL=\"http://localhost:$PORT\"\necho \"[Hook] Dev server running at $LOCAL_URL\"\n\n# Optional: Create a public tunnel (uncomment to enable)\n# Requires ngrok, cloudflared, or another tunneling tool\n\n# Example with cloudflared:\n# TUNNEL_URL=$(cloudflared tunnel --url \"$LOCAL_URL\" 2>&1 | \\\n#   grep -oP 'https://[a-z0-9-]+\\.trycloudflare\\.com' | head -1)\n\n# Example with ngrok:\n# TUNNEL_URL=$(ngrok http $PORT --log=stdout 2>&1 | \\\n#   grep -oP 'url=https://[^\"]+' | head -1 | cut -d= -f2)\n\n# For now, just use local URL (uncomment tunnel code above to enable)\nFINAL_URL=\"$LOCAL_URL\"\n\n# Report status back to dmux\ncurl -s -X PUT \"$API_URL\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"{\\\"status\\\": \\\"running\\\", \\\"url\\\": \\\"$FINAL_URL\\\"}\" > /dev/null\n\necho \"[Hook] Dev server ready at: $FINAL_URL\"\necho \"[Hook] Dev server PID: $DEV_PID\"\necho \"[Hook] Log file: $LOG_FILE\"\n";
+/**
+ * Example: run_test hook
+ */
+export declare const EXAMPLE_RUN_TEST = "#!/bin/bash\n# Example: run_test hook\n#\n# This hook runs tests and reports the status back to dmux via the HTTP API.\n# Status updates appear in real-time in the dmux UI.\n\nset -e\n\necho \"[Hook] Running tests for $DMUX_SLUG\"\n\ncd \"$DMUX_WORKTREE_PATH\"\nAPI_URL=\"http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/test\"\n\n# Update status: running\ncurl -s -X PUT \"$API_URL\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"status\": \"running\"}' > /dev/null\n\necho \"[Hook] Running test suite...\"\n\n# Capture test output\nOUTPUT_FILE=\"/tmp/dmux-test-$DMUX_PANE_ID.txt\"\n\n# Run tests (adjust command for your project)\n# Examples:\n#   - pnpm test\n#   - npm test\n#   - vitest run\n#   - jest\n#   - pytest\n#   - cargo test\nif pnpm test > \"$OUTPUT_FILE\" 2>&1; then\n  STATUS=\"passed\"\n  echo \"[Hook] Tests passed \u2713\"\nelse\n  STATUS=\"failed\"\n  echo \"[Hook] Tests failed \u2717\"\nfi\n\n# Get output (truncate if too long)\nOUTPUT=$(head -c 5000 \"$OUTPUT_FILE\")\n\n# Report results back to dmux\ncurl -s -X PUT \"$API_URL\" \\\n  -H \"Content-Type: application/json\" \\\n  -d \"$(jq -n \\\n    --arg status \"$STATUS\" \\\n    --arg output \"$OUTPUT\" \\\n    '{status: $status, output: $output}')\" > /dev/null\n\n# Cleanup\nrm -f \"$OUTPUT_FILE\"\n\necho \"[Hook] Test results reported to dmux\"\n\n# Exit with test status\nif [ \"$STATUS\" = \"passed\" ]; then\n  exit 0\nelse\n  exit 1\nfi\n";
+/**
+ * Example: post_merge hook
+ */
+export declare const EXAMPLE_POST_MERGE = "#!/bin/bash\n# Example: post_merge hook\n#\n# This hook runs after a successful merge into the target branch.\n# Use it to trigger deployments, close issues, notify teams, etc.\n\nset -e\n\necho \"[Hook] Post-merge processing for $DMUX_SLUG \u2192 $DMUX_TARGET_BRANCH\"\n\ncd \"$DMUX_ROOT\"\n\n# Push to remote if merging to main/master\nif [ \"$DMUX_TARGET_BRANCH\" = \"main\" ] || [ \"$DMUX_TARGET_BRANCH\" = \"master\" ]; then\n  echo \"[Hook] Pushing to origin/$DMUX_TARGET_BRANCH\"\n  git push origin \"$DMUX_TARGET_BRANCH\"\n\n  # Optional: Trigger deployment\n  # if [ -n \"$VERCEL_TOKEN\" ]; then\n  #   echo \"[Hook] Triggering Vercel deployment...\"\n  #   curl -X POST \"https://api.vercel.com/v1/deployments\" \\\n  #     -H \"Authorization: Bearer $VERCEL_TOKEN\" \\\n  #     -H \"Content-Type: application/json\" \\\n  #     -d '{\n  #       \"name\": \"my-project\",\n  #       \"gitSource\": {\n  #         \"type\": \"github\",\n  #         \"ref\": \"main\"\n  #       }\n  #     }'\n  # fi\nfi\n\n# Close related GitHub issue (if prompt contains #123 format)\nISSUE_NUM=$(echo \"$DMUX_PROMPT\" | grep -oP '#\\K\\d+' | head -1)\nif [ -n \"$ISSUE_NUM\" ]; then\n  echo \"[Hook] Closing GitHub issue #$ISSUE_NUM\"\n  if command -v gh &> /dev/null; then\n    gh issue close \"$ISSUE_NUM\" \\\n      -c \"Resolved in branch $DMUX_SLUG, merged to $DMUX_TARGET_BRANCH\" \\\n      2>/dev/null || echo \"[Hook] Warning: Failed to close issue (maybe already closed?)\"\n  else\n    echo \"[Hook] GitHub CLI (gh) not found, skipping issue close\"\n  fi\nfi\n\n# Send notification to Slack\n# if [ -n \"$SLACK_WEBHOOK\" ]; then\n#   echo \"[Hook] Sending Slack notification\"\n#   curl -s -X POST \"$SLACK_WEBHOOK\" \\\n#     -H \"Content-Type: application/json\" \\\n#     -d \"{\n#       \\\"text\\\": \\\"Merged: $DMUX_SLUG \u2192 $DMUX_TARGET_BRANCH\\\",\n#       \\\"blocks\\\": [\n#         {\n#           \\\"type\\\": \\\"section\\\",\n#           \\\"text\\\": {\n#             \\\"type\\\": \\\"mrkdwn\\\",\n#             \\\"text\\\": \\\"*Branch Merged* :rocket:\\n\\n*From:* \\`$DMUX_SLUG\\`\\n*To:* \\`$DMUX_TARGET_BRANCH\\`\\n*Task:* $DMUX_PROMPT\\\"\n#           }\n#         }\n#       ]\n#     }\" > /dev/null\n# fi\n\necho \"[Hook] Post-merge processing complete\"\n";
+/**
+ * All embedded examples for easy iteration
+ */
+export declare const EXAMPLE_HOOKS: {
+    'worktree_created.example': string;
+    'run_dev.example': string;
+    'run_test.example': string;
+    'post_merge.example': string;
+};
+//# sourceMappingURL=hooksDocs.d.ts.map

package/dist/utils/hooksDocs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooksDocs.d.ts","sourceRoot":"","sources":["../../src/utils/hooksDocs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,svYAAY,CAAC;AAE7C;;GAEG;AACH,eAAO,MAAM,YAAY,03CAqDxB,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wBAAwB,wxCAwCpC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,2+DA8D3B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,86CA6D5B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,yvEAkE9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;CAKzB,CAAC"}

package/dist/utils/hooksDocs.js

@@ -0,0 +1,325 @@
+/**
+ * Embedded Hooks Documentation
+ *
+ * This file contains all documentation that gets written to .dmux-hooks/
+ * when the directory is initialized. The AGENTS_MD content is auto-generated
+ * and imported from generated-agents-doc.ts
+ */
+import { AGENTS_MD } from './generated-agents-doc.js';
+/**
+ * Main documentation - gets written as both AGENTS.md and CLAUDE.md
+ * Different agents look for different filenames, but content is identical
+ */
+export const HOOKS_DOCUMENTATION = AGENTS_MD;
+/**
+ * README for the .dmux-hooks/ directory
+ */
+export const HOOKS_README = `# dmux Hooks
+
+This directory contains hooks that run automatically at key lifecycle events in dmux.
+
+## Quick Start
+
+1. **Read the documentation**:
+   - \`AGENTS.md\` - Complete reference (for any AI agent)
+   - \`CLAUDE.md\` - Same content (Claude Code looks for this filename)
+
+2. **Check examples**:
+   - \`examples/\` directory contains starter templates
+
+3. **Create a hook**:
+   \`\`\`bash
+   touch worktree_created
+   chmod +x worktree_created
+   nano worktree_created
+   \`\`\`
+
+4. **Test it**:
+   \`\`\`bash
+   export DMUX_ROOT="\$(pwd)"
+   export DMUX_WORKTREE_PATH="\$(pwd)"
+   ./worktree_created
+   \`\`\`
+
+## Available Hooks
+
+- \`before_pane_create\` - Before pane creation
+- \`pane_created\` - After pane created
+- \`worktree_created\` - After worktree setup
+- \`before_pane_close\` - Before closing
+- \`pane_closed\` - After closed
+- \`before_worktree_remove\` - Before worktree removal
+- \`worktree_removed\` - After worktree removed
+- \`pre_merge\` - Before merge
+- \`post_merge\` - After merge
+- \`run_test\` - When running tests
+- \`run_dev\` - When starting dev server
+
+## Documentation
+
+See \`AGENTS.md\` or \`CLAUDE.md\` for complete documentation including:
+- Environment variables
+- HTTP callback API
+- Common patterns
+- Best practices
+- Testing strategies
+
+## Note
+
+This directory is **version controlled**. Hooks you create here will be shared with your team.
+`;
+/**
+ * Example: worktree_created hook
+ */
+export const EXAMPLE_WORKTREE_CREATED = `#!/bin/bash
+# Example: worktree_created hook
+#
+# This hook runs after a new worktree is created and the agent is launched.
+# Use it to set up the worktree environment (install deps, copy configs, etc.)
+
+set -e  # Exit on error
+
+echo "[Hook] Setting up worktree: $DMUX_SLUG"
+
+cd "$DMUX_WORKTREE_PATH"
+
+# Install dependencies in background (don't block dmux)
+if [ -f "pnpm-lock.yaml" ]; then
+  echo "[Hook] Installing dependencies with pnpm..."
+  pnpm install --prefer-offline &
+elif [ -f "package-lock.json" ]; then
+  echo "[Hook] Installing dependencies with npm..."
+  npm install &
+elif [ -f "yarn.lock" ]; then
+  echo "[Hook] Installing dependencies with yarn..."
+  yarn install &
+fi
+
+# Copy environment file if it exists
+if [ -f "$DMUX_ROOT/.env.local" ]; then
+  echo "[Hook] Copying .env.local"
+  cp "$DMUX_ROOT/.env.local" "$DMUX_WORKTREE_PATH/.env.local"
+fi
+
+# Set custom git config for this worktree
+echo "[Hook] Configuring git"
+git config user.name "dmux-agent/$DMUX_SLUG"
+git config user.email "agent@dmux.local"
+
+# Create a log entry
+echo "[\$(date)] Created worktree: $DMUX_SLUG | Agent: $DMUX_AGENT | Prompt: $DMUX_PROMPT" \\
+  >> "$DMUX_ROOT/.dmux/worktree_history.log"
+
+echo "[Hook] Worktree setup complete!"
+`;
+/**
+ * Example: run_dev hook
+ */
+export const EXAMPLE_RUN_DEV = `#!/bin/bash
+# Example: run_dev hook
+#
+# This hook starts a dev server and optionally creates a tunnel for sharing.
+# It reports the server URL back to dmux via the HTTP API.
+
+set -e
+
+echo "[Hook] Starting dev server for $DMUX_SLUG"
+
+cd "$DMUX_WORKTREE_PATH"
+API_URL="http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/dev"
+
+# Update status: starting
+curl -s -X PUT "$API_URL" \\
+  -H "Content-Type: application/json" \\
+  -d '{"status": "running"}' > /dev/null
+
+# Start dev server in background
+# Adjust the command for your project (pnpm dev, npm run dev, vite, etc.)
+LOG_FILE="/tmp/dmux-dev-$DMUX_PANE_ID.log"
+pnpm dev > "$LOG_FILE" 2>&1 &
+DEV_PID=$!
+
+# Wait for server to be ready
+echo "[Hook] Waiting for dev server to start..."
+sleep 5
+
+# Detect port from log output
+# Adjust the grep pattern for your dev server's output format
+PORT=\$(grep -oP '(?<=localhost:)\\d+' "$LOG_FILE" | head -1)
+
+if [ -z "$PORT" ]; then
+  echo "[Hook] Warning: Could not detect port from logs, using default 3000"
+  PORT=3000
+fi
+
+LOCAL_URL="http://localhost:$PORT"
+echo "[Hook] Dev server running at $LOCAL_URL"
+
+# Optional: Create a public tunnel (uncomment to enable)
+# Requires ngrok, cloudflared, or another tunneling tool
+
+# Example with cloudflared:
+# TUNNEL_URL=\$(cloudflared tunnel --url "$LOCAL_URL" 2>&1 | \\
+#   grep -oP 'https://[a-z0-9-]+\\.trycloudflare\\.com' | head -1)
+
+# Example with ngrok:
+# TUNNEL_URL=\$(ngrok http $PORT --log=stdout 2>&1 | \\
+#   grep -oP 'url=https://[^"]+' | head -1 | cut -d= -f2)
+
+# For now, just use local URL (uncomment tunnel code above to enable)
+FINAL_URL="$LOCAL_URL"
+
+# Report status back to dmux
+curl -s -X PUT "$API_URL" \\
+  -H "Content-Type: application/json" \\
+  -d "{\\"status\\": \\"running\\", \\"url\\": \\"$FINAL_URL\\"}" > /dev/null
+
+echo "[Hook] Dev server ready at: $FINAL_URL"
+echo "[Hook] Dev server PID: $DEV_PID"
+echo "[Hook] Log file: $LOG_FILE"
+`;
+/**
+ * Example: run_test hook
+ */
+export const EXAMPLE_RUN_TEST = `#!/bin/bash
+# Example: run_test hook
+#
+# This hook runs tests and reports the status back to dmux via the HTTP API.
+# Status updates appear in real-time in the dmux UI.
+
+set -e
+
+echo "[Hook] Running tests for $DMUX_SLUG"
+
+cd "$DMUX_WORKTREE_PATH"
+API_URL="http://localhost:$DMUX_SERVER_PORT/api/panes/$DMUX_PANE_ID/test"
+
+# Update status: running
+curl -s -X PUT "$API_URL" \\
+  -H "Content-Type: application/json" \\
+  -d '{"status": "running"}' > /dev/null
+
+echo "[Hook] Running test suite..."
+
+# Capture test output
+OUTPUT_FILE="/tmp/dmux-test-$DMUX_PANE_ID.txt"
+
+# Run tests (adjust command for your project)
+# Examples:
+#   - pnpm test
+#   - npm test
+#   - vitest run
+#   - jest
+#   - pytest
+#   - cargo test
+if pnpm test > "$OUTPUT_FILE" 2>&1; then
+  STATUS="passed"
+  echo "[Hook] Tests passed ✓"
+else
+  STATUS="failed"
+  echo "[Hook] Tests failed ✗"
+fi
+
+# Get output (truncate if too long)
+OUTPUT=\$(head -c 5000 "$OUTPUT_FILE")
+
+# Report results back to dmux
+curl -s -X PUT "$API_URL" \\
+  -H "Content-Type: application/json" \\
+  -d "\$(jq -n \\
+    --arg status "$STATUS" \\
+    --arg output "$OUTPUT" \\
+    '{status: \$status, output: \$output}')" > /dev/null
+
+# Cleanup
+rm -f "$OUTPUT_FILE"
+
+echo "[Hook] Test results reported to dmux"
+
+# Exit with test status
+if [ "$STATUS" = "passed" ]; then
+  exit 0
+else
+  exit 1
+fi
+`;
+/**
+ * Example: post_merge hook
+ */
+export const EXAMPLE_POST_MERGE = `#!/bin/bash
+# Example: post_merge hook
+#
+# This hook runs after a successful merge into the target branch.
+# Use it to trigger deployments, close issues, notify teams, etc.
+
+set -e
+
+echo "[Hook] Post-merge processing for $DMUX_SLUG → $DMUX_TARGET_BRANCH"
+
+cd "$DMUX_ROOT"
+
+# Push to remote if merging to main/master
+if [ "$DMUX_TARGET_BRANCH" = "main" ] || [ "$DMUX_TARGET_BRANCH" = "master" ]; then
+  echo "[Hook] Pushing to origin/$DMUX_TARGET_BRANCH"
+  git push origin "$DMUX_TARGET_BRANCH"
+
+  # Optional: Trigger deployment
+  # if [ -n "$VERCEL_TOKEN" ]; then
+  #   echo "[Hook] Triggering Vercel deployment..."
+  #   curl -X POST "https://api.vercel.com/v1/deployments" \\
+  #     -H "Authorization: Bearer $VERCEL_TOKEN" \\
+  #     -H "Content-Type: application/json" \\
+  #     -d '{
+  #       "name": "my-project",
+  #       "gitSource": {
+  #         "type": "github",
+  #         "ref": "main"
+  #       }
+  #     }'
+  # fi
+fi
+
+# Close related GitHub issue (if prompt contains #123 format)
+ISSUE_NUM=\$(echo "$DMUX_PROMPT" | grep -oP '#\\K\\d+' | head -1)
+if [ -n "$ISSUE_NUM" ]; then
+  echo "[Hook] Closing GitHub issue #$ISSUE_NUM"
+  if command -v gh &> /dev/null; then
+    gh issue close "$ISSUE_NUM" \\
+      -c "Resolved in branch $DMUX_SLUG, merged to $DMUX_TARGET_BRANCH" \\
+      2>/dev/null || echo "[Hook] Warning: Failed to close issue (maybe already closed?)"
+  else
+    echo "[Hook] GitHub CLI (gh) not found, skipping issue close"
+  fi
+fi
+
+# Send notification to Slack
+# if [ -n "$SLACK_WEBHOOK" ]; then
+#   echo "[Hook] Sending Slack notification"
+#   curl -s -X POST "$SLACK_WEBHOOK" \\
+#     -H "Content-Type: application/json" \\
+#     -d "{
+#       \\"text\\": \\"Merged: $DMUX_SLUG → $DMUX_TARGET_BRANCH\\",
+#       \\"blocks\\": [
+#         {
+#           \\"type\\": \\"section\\",
+#           \\"text\\": {
+#             \\"type\\": \\"mrkdwn\\",
+#             \\"text\\": \\"*Branch Merged* :rocket:\\n\\n*From:* \\\`$DMUX_SLUG\\\`\\n*To:* \\\`$DMUX_TARGET_BRANCH\\\`\\n*Task:* $DMUX_PROMPT\\"
+#           }
+#         }
+#       ]
+#     }" > /dev/null
+# fi
+
+echo "[Hook] Post-merge processing complete"
+`;
+/**
+ * All embedded examples for easy iteration
+ */
+export const EXAMPLE_HOOKS = {
+    'worktree_created.example': EXAMPLE_WORKTREE_CREATED,
+    'run_dev.example': EXAMPLE_RUN_DEV,
+    'run_test.example': EXAMPLE_RUN_TEST,
+    'post_merge.example': EXAMPLE_POST_MERGE,
+};
+//# sourceMappingURL=hooksDocs.js.map

package/dist/utils/hooksDocs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooksDocs.js","sourceRoot":"","sources":["../../src/utils/hooksDocs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqD3B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwCvC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8D9B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D/B,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkEjC,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG;IAC3B,0BAA0B,EAAE,wBAAwB;IACpD,iBAAiB,EAAE,eAAe;IAClC,kBAAkB,EAAE,gBAAgB;IACpC,oBAAoB,EAAE,kBAAkB;CACzC,CAAC"}

package/dist/utils/paneCapture.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Captures the last N lines from a tmux pane, automatically skipping trailing blank lines.
+ * If the captured content ends with blank lines, it will fetch more lines to ensure
+ * we get actual content.
+ *
+ * @param paneId - The tmux pane ID to capture from
+ * @param lines - Number of non-blank lines to capture (default: 50)
+ * @param maxAttempts - Maximum number of fetch attempts to find content (default: 5)
+ * @returns The captured content with trailing blank lines removed, or empty string on failure
+ */
+export declare function capturePaneContent(paneId: string, lines?: number, maxAttempts?: number): string;
+/**
+ * Captures the last N lines from a tmux pane without filtering blank lines.
+ * Use this when you specifically want raw output including blanks.
+ *
+ * @param paneId - The tmux pane ID to capture from
+ * @param lines - Number of lines to capture (default: 50)
+ * @returns The raw captured content, or empty string on failure
+ */
+export declare function capturePaneContentRaw(paneId: string, lines?: number): string;
+//# sourceMappingURL=paneCapture.d.ts.map