feat: Add PreTeleport and PostTeleport hook events

Add documentation and examples for new teleport hooks that allow users to automate workflows when sessions transfer between web and CLI: - PreTeleport: Runs before teleporting (stash work, sync state) - PostTeleport: Runs after teleporting (pull changes, start dev servers) This addresses the common workflow where users teleport from web to CLI and need to run setup commands like `yarn dev:staging`. Slack thread: https://anthropic.slack.com/archives/C096H3HP75G/p1765833639134099?thread_ts=1765833353.488839&cid=C096H3HP75G
2026-04-28 16:47:36 +00:00 · 2025-12-15 21:25:55 +00:00
parent eb87245010
commit fee53699c3
4 changed files with 291 additions and 1 deletions
--- a/plugins/plugin-dev/skills/hook-development/SKILL.md
+++ b/plugins/plugin-dev/skills/hook-development/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: Hook Development
-description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
+description: This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification, PreTeleport, PostTeleport). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
 version: 0.1.0
 ---

@@ -275,6 +275,108 @@ Execute before context compaction. Use to add critical information to preserve.

 Execute when Claude sends notifications. Use to react to user notifications.

+### PreTeleport
+
+Execute before a session teleports (transfers from web to CLI or vice versa). Use to prepare the environment, sync state, or validate teleport conditions.
+
+**Example:**
+```json
+{
+  "PreTeleport": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-teleport.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Example script (pre-teleport.sh):**
+```bash
+#!/bin/bash
+# Stash any uncommitted changes before teleporting
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+if [ -d ".git" ] && [ -n "$(git status --porcelain)" ]; then
+  echo "📦 Stashing uncommitted changes before teleport..."
+  git stash push -m "pre-teleport-stash-$(date +%s)"
+fi
+```
+
+**Input fields:**
+- `source`: The origin of the teleport ("web" or "cli")
+- `destination`: Where the session is going ("web" or "cli")
+- `branch`: The git branch being teleported (if applicable)
+
+**Use for:**
+- Stashing uncommitted work before teleporting
+- Syncing local state with remote
+- Validating prerequisites before teleport
+- Cleaning up temporary files
+
+### PostTeleport
+
+Execute after a session successfully teleports. Use to set up the environment in the new context, run dev servers, or restore state.
+
+**Example:**
+```json
+{
+  "PostTeleport": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/post-teleport.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Example script (post-teleport.sh):**
+```bash
+#!/bin/bash
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Pull latest changes from the teleported branch
+if [ -d ".git" ]; then
+  echo "🔄 Pulling latest changes..."
+  git pull origin "$(git branch --show-current)" 2>/dev/null || true
+fi
+
+# Install dependencies if needed
+if [ -f "package.json" ]; then
+  echo "📦 Installing dependencies..."
+  npm install --silent
+fi
+
+# Start dev server (example for common workflow)
+if [ -f "package.json" ] && grep -q '"dev"' package.json; then
+  echo "🚀 Starting dev server..."
+  npm run dev &
+fi
+```
+
+**Input fields:**
+- `source`: Where the session came from ("web" or "cli")
+- `destination`: The current context ("web" or "cli")
+- `branch`: The git branch that was teleported
+- `teleport_success`: Boolean indicating if teleport completed successfully
+
+**Use for:**
+- Pulling latest changes after teleporting
+- Installing/updating dependencies
+- Starting development servers
+- Restoring stashed work
+- Running project-specific setup scripts
+
 ## Hook Output Format

 ### Standard Output (All Hooks)
@@ -642,6 +744,8 @@ echo "$output" | jq .
 | SessionEnd | Session ends | Cleanup, logging |
 | PreCompact | Before compact | Preserve context |
 | Notification | User notified | Logging, reactions |
+| PreTeleport | Before teleport | Stash work, sync state |
+| PostTeleport | After teleport | Setup env, start servers |

 ### Best Practices

@@ -679,6 +783,8 @@ Working examples in `examples/`:
 - **`validate-write.sh`** - File write validation example
 - **`validate-bash.sh`** - Bash command validation example
 - **`load-context.sh`** - SessionStart context loading example
+- **`pre-teleport.sh`** - PreTeleport state preservation example
+- **`post-teleport.sh`** - PostTeleport environment setup example

 ### Utility Scripts

--- a/plugins/plugin-dev/skills/hook-development/examples/post-teleport.sh
+++ b/plugins/plugin-dev/skills/hook-development/examples/post-teleport.sh
@@ -0,0 +1,57 @@
+#!/bin/bash
+# Example PostTeleport hook for setting up environment after teleporting
+# This script pulls changes, installs dependencies, and starts dev server
+
+set -euo pipefail
+
+# Navigate to project directory
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+echo "Setting up environment after teleport..."
+
+# Pull latest changes if in a git repository
+if [ -d ".git" ]; then
+  current_branch=$(git branch --show-current)
+  echo "🔄 Pulling latest changes for branch: $current_branch"
+  git pull origin "$current_branch" 2>/dev/null || echo "Could not pull (may be offline or no upstream)"
+
+  # Check for stashed changes from pre-teleport
+  if git stash list | grep -q "pre-teleport-stash"; then
+    echo "📦 Restoring stashed changes from pre-teleport..."
+    git stash pop || echo "Could not restore stash (may have conflicts)"
+  fi
+fi
+
+# Install dependencies based on project type
+if [ -f "package.json" ]; then
+  echo "📦 Installing Node.js dependencies..."
+  npm install --silent 2>/dev/null || npm install
+fi
+
+if [ -f "requirements.txt" ]; then
+  echo "🐍 Installing Python dependencies..."
+  pip install -r requirements.txt --quiet 2>/dev/null || pip install -r requirements.txt
+fi
+
+if [ -f "Cargo.toml" ]; then
+  echo "🦀 Building Rust project..."
+  cargo build 2>/dev/null || true
+fi
+
+# Start development server if available
+if [ -f "package.json" ]; then
+  # Check for common dev server scripts
+  if grep -q '"dev:staging"' package.json; then
+    echo "🚀 Starting staging dev server..."
+    npm run dev:staging &
+  elif grep -q '"dev"' package.json; then
+    echo "🚀 Starting dev server..."
+    npm run dev &
+  elif grep -q '"start"' package.json; then
+    echo "🚀 Starting server..."
+    npm start &
+  fi
+fi
+
+echo "✅ Teleport complete! Environment ready."
+exit 0
--- a/plugins/plugin-dev/skills/hook-development/examples/pre-teleport.sh
+++ b/plugins/plugin-dev/skills/hook-development/examples/pre-teleport.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# Example PreTeleport hook for preparing environment before teleporting
+# This script stashes uncommitted changes and saves state for restoration
+
+set -euo pipefail
+
+# Navigate to project directory
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+echo "Preparing for teleport..."
+
+# Check if we're in a git repository
+if [ ! -d ".git" ]; then
+  echo "Not a git repository, skipping pre-teleport preparation"
+  exit 0
+fi
+
+# Stash uncommitted changes before teleporting
+if [ -n "$(git status --porcelain)" ]; then
+  echo "📦 Stashing uncommitted changes before teleport..."
+  git stash push -m "pre-teleport-stash-$(date +%s)"
+  echo "Changes stashed successfully"
+else
+  echo "No uncommitted changes to stash"
+fi
+
+# Save current branch state for post-teleport restoration
+mkdir -p .claude
+echo "$(git branch --show-current)" > .claude/.teleport-state
+echo "Current branch saved: $(cat .claude/.teleport-state)"
+
+echo "Pre-teleport preparation complete"
+exit 0
--- a/plugins/plugin-dev/skills/hook-development/references/patterns.md
+++ b/plugins/plugin-dev/skills/hook-development/references/patterns.md
@@ -344,3 +344,97 @@ fi
 - Per-project settings
 - Team-specific rules
 - Dynamic validation criteria
+
+## Pattern 11: Teleport Workflow Automation
+
+Automate setup when teleporting sessions between web and CLI:
+
+**Pre-teleport hook (prepare for transfer):**
+```json
+{
+  "PreTeleport": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/pre-teleport.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**pre-teleport.sh:**
+```bash
+#!/bin/bash
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Stash uncommitted changes before teleporting
+if [ -d ".git" ] && [ -n "$(git status --porcelain)" ]; then
+  echo "📦 Stashing uncommitted changes..."
+  git stash push -m "pre-teleport-$(date +%s)"
+fi
+
+# Save current state for restoration
+echo "$(git branch --show-current)" > .claude/.teleport-state
+```
+
+**Post-teleport hook (set up after transfer):**
+```json
+{
+  "PostTeleport": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/post-teleport.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**post-teleport.sh:**
+```bash
+#!/bin/bash
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Pull latest changes
+if [ -d ".git" ]; then
+  echo "🔄 Pulling latest changes..."
+  git pull origin "$(git branch --show-current)" 2>/dev/null || true
+
+  # Restore stashed changes if any
+  if git stash list | grep -q "pre-teleport"; then
+    echo "📦 Restoring stashed changes..."
+    git stash pop
+  fi
+fi
+
+# Install dependencies
+if [ -f "package.json" ]; then
+  echo "📦 Installing dependencies..."
+  npm install --silent
+fi
+
+# Start dev server
+if [ -f "package.json" ] && grep -q '"dev:staging"' package.json; then
+  echo "🚀 Starting staging dev server..."
+  npm run dev:staging &
+elif [ -f "package.json" ] && grep -q '"dev"' package.json; then
+  echo "🚀 Starting dev server..."
+  npm run dev &
+fi
+
+echo "✅ Teleport complete! Environment ready."
+```
+
+**Use for:**
+- Seamless web-to-CLI workflow transitions
+- Automatic dev server startup after teleporting
+- Preserving uncommitted work across teleports
+- Environment setup automation