Claude Code Context Optimization: Hook Consolidation and Progressive Skill Disclosure

Session Date: 2026-01-19
Project: claude-dev-environment (Claude Code Configuration)
Focus: Implement context management best practices from CONTEXT_MANAGEMENT.md
Session Type: Performance Optimization

Executive Summary

Implemented comprehensive context management optimizations for Claude Code based on the newly documented best practices guide. The primary achievement was consolidating 10 separate TypeScript hooks into a unified pre-compiled JavaScript runner, eliminating the ~200-500ms tsx startup overhead per tool invocation. Additionally, created a progressive skill disclosure system with 21 configured skills and established user-level defaults via CLAUDE.md.

The hook consolidation reduced the number of shell command invocations from 10 to 5, consolidated PreToolUse matchers from 3 to 1, and PostToolUse matchers from 4 to 1. Combined with pre-compilation to JavaScript, this significantly reduces latency during Claude Code sessions.

Key Metrics:

Metric Before After Change
Hook Commands 10 5 -50%
tsx Startup Overhead ~200-500ms/call 0ms -100%
PreToolUse Matchers 3 1 -67%
PostToolUse Matchers 4 1 -75%
Stop Hooks 2 1 -50%
Skills Configured 0 21 +21
Files Changed - 38 -

Problem Statement

Analysis of the existing Claude Code configuration revealed several context management inefficiencies:

  1. No user-level CLAUDE.md - Missing baseline configuration for response style and code conventions
  2. Heavy hook overhead - 10 separate npx tsx commands, each with ~200-500ms startup time
  3. No progressive skill disclosure - 22 skills with no trigger-based loading system
  4. Conservative MCP output limit - 15,000 tokens vs recommended 25,000
  5. Multiple matchers per event - Separate matchers for MCP, Plugin, and Agent tools

Impact Before: Each tool invocation triggered multiple tsx processes, adding significant latency to the development workflow.

Implementation Details

1. User-Level CLAUDE.md

File: ~/.claude/CLAUDE.md

Created lean user-level defaults (~500 tokens):


## Response Guidelines
- Concise, actionable responses
- Bullet points over paragraphs
- No emojis unless requested

## Code Style
- TypeScript preferred
- ES modules (not CommonJS)
- 2-space indentation

## Context Management
- Use subagents for verbose operations
- Truncate bash output with | head -100

2. Unified Hook Runner

File: hooks/hook-runner.ts

Created single entry point that routes to appropriate handlers:

import { handleSessionStart } from './handlers/session-start.js';
import { handlePreTool } from './handlers/pre-tool.js';
import { handlePostTool } from './handlers/post-tool.js';
import { handleStop } from './handlers/stop.js';
import { handleUserPrompt } from './handlers/user-prompt.js';

async function main(): Promise<void> {
  const hookType = process.argv[2];

  switch (hookType) {
    case 'session-start': await handleSessionStart(hookInput); break;
    case 'pre-tool': await handlePreTool(hookInput, subType); break;
    case 'post-tool': await handlePostTool(hookInput, subType); break;
    case 'stop': await handleStop(hookInput, subType); break;
    case 'user-prompt': await handleUserPrompt(hookInput); break;
  }
}

3. Consolidated Handler Modules

Created 5 handler modules that combine related functionality:

Handler Combines Lines
handlers/session-start.ts session-start-otel 98
handlers/pre-tool.ts mcp-pre + plugin-pre + agent-pre 210
handlers/post-tool.ts mcp-post + plugin-post + agent-post + tsc-check 280
handlers/stop.ts stop-build-check + error-handling-reminder 320
handlers/user-prompt.ts skill-activation-prompt 175

4. Pre-Compilation to JavaScript

File: hooks/tsconfig.json

Updated to compile unified system:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "outDir": "./dist"
  },
  "include": ["hook-runner.ts", "handlers/**/*.ts", "lib/**/*.ts"]
}

Build command: npm run build

5. Updated Settings Configuration

File: ~/.claude/settings.json

Replaced 10 tsx commands with 5 node commands:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "command": "node ~/.claude/hooks/dist/hook-runner.js session-start"
      }]
    }],
    "PreToolUse": [{
      "matcher": "mcp__.*|Skill|Task",
      "hooks": [{
        "command": "node ~/.claude/hooks/dist/hook-runner.js pre-tool"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit|MultiEdit|mcp__.*|Skill|Task",
      "hooks": [{
        "command": "node ~/.claude/hooks/dist/hook-runner.js post-tool"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "command": "node ~/.claude/hooks/dist/hook-runner.js stop"
      }]
    }],
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "command": "node ~/.claude/hooks/dist/hook-runner.js user-prompt"
      }]
    }]
  },
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:5",
    "MAX_MCP_OUTPUT_TOKENS": "25000"
  }
}

6. Progressive Skill Disclosure

File: ~/.claude/skills/skill-rules.json

Configured 21 skills with trigger-based loading:

{
  "version": "1.0",
  "skills": {
    "backend-dev-guidelines": {
      "type": "domain",
      "enforcement": "suggest",
      "priority": "high",
      "promptTriggers": {
        "keywords": ["express", "route", "controller", "service"],
        "intentPatterns": ["(create|add).*?(route|endpoint|controller)"]
      },
      "fileTriggers": {
        "pathPatterns": ["**/src/routes/**/*.ts", "**/src/controllers/**/*.ts"]
      },
      "skipConditions": { "sessionSkillUsed": true }
    }
  }
}

Skills by Priority:

Priority Count Examples
High 6 backend-dev, frontend-dev, error-tracking, bug-detective
Medium 12 gtm-tags, cicd, api-cost-tracking, supabase-oauth
Low 3 documentation-cleanup, session-report, repository-analyzer

Key Decisions and Trade-offs

Decision 1: Unified Runner vs Separate Scripts

Choice: Single entry point with handler modules Rationale: Eliminates tsx startup overhead, enables shared code, simplifies configuration Alternative Considered: Keep separate scripts but pre-compile each Trade-off: Slightly more complex routing logic, but significant performance gain

Decision 2: Pre-compilation vs Runtime TypeScript

Choice: Pre-compile to JavaScript with tsc Rationale: Node.js native execution ~200-500ms faster than tsx Alternative Considered: Continue using tsx for development convenience Trade-off: Requires rebuild after changes (npm run build)

Decision 3: Combined Matchers

Choice: Single regex matcher combining multiple tools (e.g., mcp__.*|Skill|Task) Rationale: Single hook invocation instead of multiple per tool category Alternative Considered: Keep separate matchers for granular control Trade-off: All matching tools run same handler (handler routes internally)

Testing and Verification

Hook Runner Test

$ echo '{"session_id": "test", "tool_name": "Task", "tool_input": {"subagent_type": "Explore"}}' \
  | node ~/.claude/hooks/dist/hook-runner.js pre-tool

OpenTelemetry: Traces exporting to https://ingest.us.signoz.cloud/v1/traces
OpenTelemetry: Metrics exporting to https://ingest.us.signoz.cloud/v1/metrics
OpenTelemetry: Logs exporting to https://ingest.us.signoz.cloud/v1/logs
🤖 Agent: Explore [exploration]

Build Verification

$ cd ~/.claude/hooks && npm run build
> claude-hooks@1.0.0 build
> tsc

$ ls dist/handlers/
post-tool.js    pre-tool.js    session-start.js    stop.js    user-prompt.js

Files Modified

Created Files (8)

File Lines Purpose
CLAUDE.md 35 User-level defaults
hooks/hook-runner.ts 75 Unified entry point
hooks/handlers/session-start.ts 98 Session initialization
hooks/handlers/pre-tool.ts 210 MCP/Plugin/Agent pre-tool
hooks/handlers/post-tool.ts 280 MCP/Plugin/Agent post-tool + TSC
hooks/handlers/stop.ts 320 Build check + error reminder
hooks/handlers/user-prompt.ts 175 Skill activation
skills/skill-rules.json 546 Progressive skill disclosure

Modified Files (5)

File Change
hooks/lib/otel-monitor.ts Fixed .js import extension
hooks/lib/otel.ts Fixed .js import extension
hooks/package.json Added build script
hooks/tsconfig.json Updated include patterns
config/settings.json Unified hook configuration

Compiled Output (27 files in dist/)

  • dist/hook-runner.js
  • dist/handlers/*.js (5 files)
  • dist/lib/*.js (4 files)
  • Legacy compatibility files (18 files)

Git Commits

Commit Description Files
9dcfd9b perf(hooks): consolidate hooks into unified runner with pre-compiled JS 38
a91b8c6 chore: update skill-rules.json and marketplace timestamps 2

Performance Impact

Estimated Latency Reduction

Scenario Before After Savings
Tool invocation (tsx) ~300ms ~50ms ~250ms
Session with 50 tools ~15s overhead ~2.5s ~12.5s
Session with 200 tools ~60s overhead ~10s ~50s

Context Management Benefits

Optimization Impact
CLAUDE.md (~500 tokens) Consistent response style
Skill rules (lazy loading) Reduced initial context
MAX_MCP_OUTPUT_TOKENS (25k) Fewer truncation issues
ENABLE_TOOL_SEARCH (auto:5) 85% MCP overhead reduction

Next Steps

Immediate

  1. ✅ Changes committed and ready for use

Short-term (Next Session)

  1. Monitor hook performance in SigNoz dashboards
  2. Fine-tune skill-rules.json triggers based on actual usage

Medium-term

  1. Consider adding more skills to progressive disclosure
  2. Document hook development workflow for future changes

References

Code Files

  • ~/.claude/hooks/hook-runner.ts - Unified entry point
  • ~/.claude/hooks/handlers/*.ts - Handler modules
  • ~/.claude/skills/skill-rules.json - Skill triggers
  • ~/.claude/CLAUDE.md - User defaults

Documentation

  • ~/.claude/docs/CONTEXT_MANAGEMENT.md - Best practices guide
  • ~/.claude/skills/skill-developer/SKILL_RULES_REFERENCE.md - Skill rules schema
  • Previous: Hook OTel instrumentation (commits 6738a10, b561cb7)