gh-overlord-z-claudeshack/skills/oracle/scripts/HOOK_SETUP.md

Oracle SessionStart Hook Setup

This guide explains how to configure Claude Code to automatically load Oracle context when sessions start.

Overview

The SessionStart hook automatically injects Oracle knowledge into every new or resumed Claude Code session, ensuring Claude always has access to:

• Critical gotchas and warnings
• Recent corrections
• High-priority patterns and solutions
• Project-specific preferences

Quick Setup

1. Add Hook to Claude Code Settings

Edit your Claude Code settings file (location varies by platform):

• macOS: ~/Library/Application Support/Claude/settings.json
• Linux: ~/.config/Claude/settings.json
• Windows: %APPDATA%\Claude\settings.json

Add this configuration to the hooks section:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "python /full/path/to/ClaudeShack/skills/oracle/scripts/session_start_hook.py"
          }
        ]
      }
    ]
  }
}

Important: Replace /full/path/to/ClaudeShack with the actual absolute path to your ClaudeShack directory.

2. Test the Hook

Test that the hook works by running it manually:

cd /path/to/your/project
python /path/to/ClaudeShack/skills/oracle/scripts/session_start_hook.py --debug

You should see Oracle context output to stderr. If you see "Oracle: Not initialized", run:

python /path/to/ClaudeShack/skills/oracle/scripts/init_oracle.py

3. Start a New Session

Start a new Claude Code session. Oracle context should automatically be injected!

You'll see something like:

# Oracle Project Knowledge

Knowledge Base: 25 entries | 5 sessions recorded

## Key Knowledge

### Gotchas (Watch Out!)

- **[CRITICAL]** Database connections must be closed explicitly
- **API rate limit is 100 req/min**

### Recent Corrections

- Use textContent instead of innerHTML for user input (XSS prevention)
- Always use async/await, not callbacks

Configuration Options

Context Tier Levels

Control how much context is loaded using the ORACLE_CONTEXT_TIER environment variable:

# In your shell profile (.bashrc, .zshrc, etc.):
export ORACLE_CONTEXT_TIER=1  # Default: Critical + High priority only
export ORACLE_CONTEXT_TIER=2  # Include Medium priority
export ORACLE_CONTEXT_TIER=3  # All knowledge

Or pass it directly in the hook configuration:

{
  "type": "command",
  "command": "ORACLE_CONTEXT_TIER=2 python /path/to/session_start_hook.py"
}

Or use the CLI argument:

{
  "type": "command",
  "command": "python /path/to/session_start_hook.py --tier 2"
}

Maximum Context Length

Limit context size to avoid overwhelming the session:

export ORACLE_MAX_CONTEXT_LENGTH=5000  # Default: 5000 characters
export ORACLE_MAX_CONTEXT_LENGTH=10000 # More context
export ORACLE_MAX_CONTEXT_LENGTH=2000  # Less context

Or via CLI:

{
  "type": "command",
  "command": "python /path/to/session_start_hook.py --max-length 10000"
}

Advanced Configuration

Hook on Resume Only

To load Oracle context only when resuming sessions (not on new sessions):

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "resume",
        "hooks": [
          {
            "type": "command",
            "command": "python /path/to/session_start_hook.py --source resume"
          }
        ]
      }
    ]
  }
}

Hook on Both Startup and Resume

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "python /path/to/session_start_hook.py --source startup"
          }
        ]
      },
      {
        "matcher": "resume",
        "hooks": [
          {
            "type": "command",
            "command": "python /path/to/session_start_hook.py --source resume"
          }
        ]
      }
    ]
  }
}

Per-Project Configuration

If you work with multiple projects, you can use different configurations:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "pathPattern": "**/my-critical-project/**",
        "hooks": [
          {
            "type": "command",
            "command": "ORACLE_CONTEXT_TIER=1 python /path/to/session_start_hook.py"
          }
        ]
      },
      {
        "matcher": "startup",
        "pathPattern": "**/my-casual-project/**",
        "hooks": [
          {
            "type": "command",
            "command": "ORACLE_CONTEXT_TIER=3 python /path/to/session_start_hook.py"
          }
        ]
      }
    ]
  }
}

Troubleshooting

Hook Not Running

1. Check settings file syntax: Ensure valid JSON (no trailing commas, proper quotes)
2. Check paths: Use absolute paths, not relative
3. Check permissions: Ensure script is executable (chmod +x session_start_hook.py)
4. Test manually: Run the script from your project directory

No Context Showing

1. Verify Oracle is initialized: Run ls -la .oracle/ in your project
2. Check if knowledge exists: Run python /path/to/query_knowledge.py --summary
3. Test hook in debug mode: python session_start_hook.py --debug

Context Too Large

Reduce context with:

• Lower tier level (ORACLE_CONTEXT_TIER=1)
• Smaller max length (ORACLE_MAX_CONTEXT_LENGTH=3000)
• Prioritize your knowledge entries (set priority to low for less critical items)

Context Not Relevant

The SessionStart hook loads critical/high priority items only. To get task-specific context:

1. Use the oracle skill manually: /oracle (if available)
2. Run: python /path/to/generate_context.py --task "your task description"
3. Query specific knowledge: python /path/to/query_knowledge.py "keywords"

Best Practices

1. Keep critical items truly critical: Only mark security, data loss, and breaking issues as critical
2. Regular cleanup: Review and remove outdated knowledge monthly
3. Use tags: Tag knowledge for better organization
4. Record sessions: Use record_session.py after important sessions
5. Analyze history: Run analyze_history.py --auto-populate weekly to mine conversation history

Hook Output Format

The hook outputs JSON in this format:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "# Oracle Project Knowledge\n\n..."
  }
}

Claude Code reads the additionalContext field and injects it into the session context.

Verification

To verify the hook is working:

1. Start a new session
2. Ask Claude: "What do you know about this project from Oracle?"
3. Claude should reference the injected knowledge

Disable Hook Temporarily

To temporarily disable the hook without removing configuration:

1. Add a condition to the matcher that won't match
2. Or comment out the hook in settings (use // in JSONC format if supported)
3. Or set environment variable: export ORACLE_HOOK_DISABLED=1

Related Scripts

• init_oracle.py - Initialize Oracle for a project
• record_session.py - Record session learnings
• query_knowledge.py - Query knowledge base
• generate_context.py - Generate context summaries
• analyze_history.py - Mine conversation history

Support

For issues or questions:

1. Check the troubleshooting section above
2. Review Claude Code hooks documentation
3. Test the script manually with --debug flag
4. Check Claude Code logs for hook execution errors