gh-awudevelop-claude-plugins-session/commands/setup.md

You are helping the user configure session plugin hooks in their project's .claude/settings.json file.

Task: Setup Session Plugin Hooks

This command manages the automatic configuration of session plugin hooks that enable auto-tracking of sessions, user interactions, and file modifications.

IMPORTANT: This command uses the session CLI tool to perform hook management operations safely with atomic writes and backups.

Parse Command Arguments

Extract the operation from the command arguments. Format: /session:setup [options]

Supported options:

• No arguments: Install/configure hooks (default)
• --permissions: Install hooks + permission bypasses (eliminates ALL prompts)
• --remove: Remove hooks from settings.json
• --status: Show current hook and permission configuration
• --force-cleanup: Force cleanup of orphaned hooks
• --dry-run: Preview changes without applying them

Step 1: Determine Operation Mode

1. Check arguments to determine which operation to perform:
   • Install mode (default/no args): Add hooks to settings.json
   • Remove mode (--remove): Remove hooks from settings.json
   • Status mode (--status): Show current configuration
   • Cleanup mode (--force-cleanup): Clean up orphaned hooks
   • Dry run (--dry-run): Can be combined with other modes to preview

Step 2: Execute CLI Command

Run the appropriate CLI command based on the operation mode:

For Install (hooks only):

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js setup-hooks

For Install (hooks + permissions):

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js setup-hooks --permissions

For Remove:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js setup-hooks --remove

For Status:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js setup-hooks --status

For Force Cleanup:

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js setup-hooks --force-cleanup

For Dry Run (example with install):

node ${CLAUDE_PLUGIN_ROOT}/cli/session-cli.js setup-hooks --dry-run

The CLI will return JSON with the operation result.

Step 3: Display Results

Parse the JSON response and display user-friendly output based on the action:

Install Success (action: "installed")

If permissions were added (permissionsRequested: true, permissionsCount > 0):

✅ Session plugin configured successfully!

📋 Hooks added to .claude/settings.json:
  ✓ SessionStart - Auto-clears session on /clear
  ✓ SessionEnd - Cleanup on Claude Code exit
  ✓ UserPromptSubmit - Tracks user interactions
  ✓ PostToolUse (Write, Edit, NotebookEdit) - Tracks file changes
  ✓ Stop - Captures Claude's responses for self-contained logs

🔓 Permissions added ({permissionsCount} entries):
  ✓ Read(.claude/sessions/**)
  ✓ Bash(git log --oneline:*)
  ✓ Bash(git status --porcelain:*)
  ✓ Bash(git diff --stat:*)
  ✓ Bash(git branch -vv:*)
  ✓ Bash(git rev-parse --abbrev-ref:*)

⚡ Result: ZERO permission prompts during:
  • /session:continue (no Read prompts, no git prompts)
  • /session:save (no Read prompts)
  • /session:status (no Read prompts)
  • All session operations run silently

💾 Backup saved: {backupPath}
📁 Settings: {settingsPath}

⚠️  IMPORTANT: Restart Claude Code for changes to take effect!
   Hooks and permissions are loaded at startup.

💡 To disable temporarily: Set "disableAllHooks": true in settings.json
💡 To remove these hooks: /session:setup --remove

If permissions were NOT added (permissionsRequested: false):

✅ Session plugin hooks configured successfully!

📋 Hooks added to .claude/settings.json:
  ✓ SessionStart - Auto-clears session on /clear
  ✓ SessionEnd - Cleanup on Claude Code exit
  ✓ UserPromptSubmit - Tracks user interactions
  ✓ PostToolUse (Write, Edit, NotebookEdit) - Tracks file changes
  ✓ Stop - Captures Claude's responses for self-contained logs

🎯 Sessions now automatically track:
  • Session state changes
  • User prompts and interactions
  • Claude's full responses
  • File modifications

💡 TIP: Eliminate ALL permission prompts during session operations!
   Run: /session:setup --permissions

   This adds safe read-only permissions for:
   • .claude/sessions/** files (Read access)
   • git commands (log, status, diff, branch)

   Result: Zero prompts during /session:continue ⚡

💾 Backup saved: {backupPath}
📁 Settings: {settingsPath}

⚠️  IMPORTANT: Restart Claude Code for hooks to take effect!
   Hooks are loaded at startup and won't activate until you restart.

💡 To disable temporarily: Set "disableAllHooks": true in settings.json
💡 To remove these hooks: /session:setup --remove

Already Configured (action: "already_configured")

ℹ️  Session plugin hooks are already configured!

✓ All session plugin hooks are properly configured in settings.json

Current hooks:
  ✓ SessionStart - Active
  ✓ UserPromptSubmit - Active
  ✓ PostToolUse - Active
  ✓ Stop - Active

💡 To reinstall: /session:setup --remove, then /session:setup
💡 To view details: /session:setup --status

Remove Success (action: "removed")

✅ Session plugin hooks removed!

📋 Removed from .claude/settings.json:
  ✓ SessionStart
  ✓ UserPromptSubmit
  ✓ PostToolUse
  ✓ Stop

💾 Backup saved: {backupPath}

⚠️  IMPORTANT: Restart Claude Code to stop hooks!
   Active hooks will continue running until you restart.

💡 Sessions still work, but automatic tracking is disabled
💡 To re-enable: /session:setup

Not Configured (action: "not_configured")

ℹ️  No session plugin hooks found

Session plugin hooks are not currently configured in settings.json

💡 To install hooks: /session:setup
💡 This will enable automatic session tracking

Status Display (action: "status")

When properly configured:

✅ Session Plugin Status

📋 Hooks configured in .claude/settings.json:

  ✓ SessionStart
    → node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js

  ✓ SessionEnd
    → node ${CLAUDE_PLUGIN_ROOT}/hooks/session-end.js

  ✓ UserPromptSubmit
    → node ${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.js

  ✓ PostToolUse (3 matchers)
    → Write: node ${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use.js
    → Edit: node ${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use.js
    → NotebookEdit: node ${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use.js

  ✓ Stop
    → node ${CLAUDE_PLUGIN_ROOT}/hooks/stop.js

📊 Hooks: {configuredHookTypes}/{totalHookTypes} hook types configured
✅ All hooks pointing to valid scripts

🔓 Permissions configured: {permissionsCount}/{totalPermissions}

{if permissionsConfigured === true}
  ✅ All session permissions configured
  • Read(.claude/sessions/**)
  • Bash(git log --oneline:*)
  • Bash(git status --porcelain:*)
  • Bash(git diff --stat:*)
  • Bash(git branch -vv:*)
  • Bash(git rev-parse --abbrev-ref:*)

  ⚡ Result: Zero prompts during session operations
{else if permissionsCount > 0 && permissionsCount < totalPermissions}
  ⚠️  Partial permissions configured ({permissionsCount}/{totalPermissions})

  💡 To add missing permissions: /session:setup --permissions
{else}
  ⚠️  No session permissions configured

  💡 To eliminate permission prompts: /session:setup --permissions
     This adds safe read-only permissions for session files and git commands
{end if}

🎯 Plugin Status: Installed & Configured

💡 To remove: /session:setup --remove

When orphaned (plugin uninstalled but hooks remain):

⚠️  Session Plugin Hooks Status

📋 Found in .claude/settings.json:

  ⚠️  SessionStart
    → node ${CLAUDE_PLUGIN_ROOT}/hooks/session-start.js
    ❌ Script not found (plugin may be uninstalled)

  ⚠️  UserPromptSubmit
    ❌ Script not found

  ⚠️  PostToolUse (3 matchers)
    ❌ All scripts not found

  ⚠️  Stop
    ❌ Script not found

🔍 Plugin Status: Not Found
❌ Hooks are orphaned (pointing to missing files)

Found {orphanedHooks.length} orphaned hook entries

🧹 Cleanup Options:
  1. Auto-cleanup: /session:setup --force-cleanup
  2. Manual cleanup: Edit .claude/settings.json
  3. Reinstall plugin to restore functionality

Cleanup Success (action: "cleaned")

✅ Orphaned hooks cleaned up!

🧹 Removed {removedCount} orphaned hook entries:
{List each orphaned hook that was removed}

💾 Backup saved: {backupPath}

⚠️  IMPORTANT: Restart Claude Code to apply cleanup!
   Settings changes take effect on next restart.

💡 Settings.json has been cleaned
💡 To reinstall hooks: /session:setup

No Orphans (action: "no_orphans")

✅ No orphaned hooks found

All hooks in settings.json are valid

💡 Everything looks good!

Error Cases

On error (success: false):

❌ Error: {error message}

{Provide helpful context based on the error:}

Common issues:
- **Malformed JSON**: settings.json has syntax errors
  → Fix: Restore from backup or manually repair JSON

- **Permission denied**: No write access to .claude/settings.json
  → Fix: Check file permissions

- **Plugin not found**: Session plugin may not be installed
  → Fix: Reinstall the session plugin

💡 To restore from backup: cp .claude/settings.json.backup .claude/settings.json
💡 Need help? Check the README or /session:setup --status

Important Notes

• Atomic Operations: All writes use atomic operations with backups
• Idempotent: Safe to run multiple times, won't create duplicates
• Portable Paths: Uses ${CLAUDE_PLUGIN_ROOT} variable for cross-platform compatibility
• Merge Strategy: Preserves existing hooks when installing
• Safety: Creates .backup file before any modifications

Usage Examples

# Install hooks only (basic setup)
/session:setup

# Install hooks + permissions (RECOMMENDED - eliminates ALL prompts)
/session:setup --permissions

# Check current status (shows hooks and permissions)
/session:setup --status

# Preview what would be installed (dry run)
/session:setup --dry-run

# Preview with permissions
/session:setup --permissions --dry-run

# Remove hooks before uninstalling plugin
/session:setup --remove

# Clean up orphaned hooks after plugin uninstall
/session:setup --force-cleanup

Recommended: Always use --permissions flag for best experience:

• Zero permission prompts during /session:continue
• Zero permission prompts during /session:save
• Zero permission prompts during /session:status
• Completely silent session operations

---

CRITICAL for Plugin Uninstallation:

Before uninstalling the session plugin, users should run:

/session:setup --remove

This ensures clean removal and prevents orphaned hook entries in settings.json.