ros/claude-code
1
0
Fork 0
mirror of https://github.com/anthropics/claude-code.git synced 2026-01-30 04:02:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: Use SessionStart teleport matcher instead of separate hooks

Browse Source 
Change approach from separate PreTeleport/PostTeleport hook events to
using SessionStart with a `teleport` matcher. This is cleaner since
teleporting to CLI starts a new session anyway.

SessionStart matchers:
- `*` - All session starts
- `teleport` - Only teleported sessions (web → CLI)
- `fresh` - Only fresh sessions (not teleported)

Removes pre-teleport.sh example since there's no pre-teleport hook.
This commit is contained in:
Claude
2025-12-15 21:43:32 +00:00
parent fee53699c3
commit 93effadd31
4 changed files with 48 additions and 173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

122
plugins/plugin-dev/skills/hook-development/SKILL.md
View File

@@ -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, PreTeleport, PostTeleport). 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", "teleport hook", 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.
version: 0.1.0
---
@@ -239,7 +239,12 @@ Execute when user submits a prompt. Use to add context, validate, or block promp
Execute when Claude Code session begins. Use to load context and set environment.
**Example:**
**Matchers for SessionStart:**
- `*` - All session starts
- `teleport` - Only when session started via teleport (web → CLI)
- `fresh` - Only for fresh sessions (not teleported)
**Example (general context loading):**
```json
{
"SessionStart": [
@@ -256,79 +261,12 @@ Execute when Claude Code session begins. Use to load context and set environment
}
```
**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:
```bash
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
```
See `examples/load-context.sh` for complete example.
### SessionEnd
Execute when session ends. Use for cleanup, logging, and state preservation.
### PreCompact
Execute before context compaction. Use to add critical information to preserve.
### Notification
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:**
**Example (teleport-specific setup):**
```json
{
"PreTeleport": [
"SessionStart": [
{
"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": "*",
"matcher": "teleport",
"hooks": [
{
"type": "command",
@@ -364,18 +302,29 @@ if [ -f "package.json" ] && grep -q '"dev"' package.json; then
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
**Special capability:** Persist environment variables using `$CLAUDE_ENV_FILE`:
```bash
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
```
**Use for:**
- Pulling latest changes after teleporting
- Installing/updating dependencies
- Starting development servers
- Restoring stashed work
- Running project-specific setup scripts
**Teleport-specific input fields:**
- `is_teleport`: Boolean indicating if this session started via teleport
- `source`: Where the session came from ("web" or "cli") - only present for teleports
- `branch`: The git branch that was teleported - only present for teleports
See `examples/load-context.sh` and `examples/post-teleport.sh` for complete examples.
### SessionEnd
Execute when session ends. Use for cleanup, logging, and state preservation.
### PreCompact
Execute before context compaction. Use to add critical information to preserve.
### Notification
Execute when Claude sends notifications. Use to react to user notifications.
## Hook Output Format
@@ -740,12 +689,10 @@ echo "$output" | jq .
| UserPromptSubmit | User input | Context, validation |
| Stop | Agent stopping | Completeness check |
| SubagentStop | Subagent done | Task validation |
| SessionStart | Session begins | Context loading |
| SessionStart | Session begins | Context loading (use `teleport` matcher for teleport-specific setup) |
| 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
@@ -783,8 +730,7 @@ 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
- **`post-teleport.sh`** - SessionStart teleport matcher setup example
### Utility Scripts

11
plugins/plugin-dev/skills/hook-development/examples/post-teleport.sh
View File

@@ -1,6 +1,7 @@
#!/bin/bash
# Example PostTeleport hook for setting up environment after teleporting
# This script pulls changes, installs dependencies, and starts dev server
# Example SessionStart hook with "teleport" matcher for setting up environment
# after teleporting from web to CLI. This script pulls changes, installs
# dependencies, and starts the dev server.
set -euo pipefail
@@ -14,12 +15,6 @@ 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

33
plugins/plugin-dev/skills/hook-development/examples/pre-teleport.sh
View File

@@ -1,33 +0,0 @@
#!/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

55
plugins/plugin-dev/skills/hook-development/references/patterns.md
View File

@@ -347,46 +347,14 @@ fi
## Pattern 11: Teleport Workflow Automation
Automate setup when teleporting sessions between web and CLI:
Automate setup when teleporting sessions from web to CLI using the `teleport` matcher:
**Pre-teleport hook (prepare for transfer):**
**SessionStart hook with teleport matcher:**
```json
{
"PreTeleport": [
"SessionStart": [
{
"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": "*",
"matcher": "teleport",
"hooks": [
{
"type": "command",
@@ -407,12 +375,6 @@ cd "$CLAUDE_PROJECT_DIR" || exit 0
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
@@ -433,8 +395,13 @@ fi
echo "✅ Teleport complete! Environment ready."
```
**Available matchers for SessionStart:**
- `*` - All session starts (both fresh and teleported)
- `teleport` - Only teleported sessions (web → CLI)
- `fresh` - Only fresh sessions (not teleported)
**Use for:**
- Seamless web-to-CLI workflow transitions
- Automatic dev server startup after teleporting
- Preserving uncommitted work across teleports
- Environment setup automation
- Pulling latest changes and installing dependencies
- Running project-specific setup scripts