Purpose

Comprehensive research on Claude Code features, architecture, and development patterns. Covers custom slash commands, GitHub automation, task delegation mechanisms (sub-agents vs skills), and performance optimization strategies for AI-assisted development workflows.

Contents

Core Documentation

  • hooks.md - Complete guide to Claude Code hooks system

    • All 10 hook events: SessionStart, Stop, PreToolUse, PostToolUse, UserPromptSubmit, etc.
    • Payload structures with session_id availability (confirmed in all hooks including Stop)
    • Hook configuration syntax, matchers, and execution behavior
    • Practical examples for session tracking, tool validation, and context injection
    • Blocking vs non-blocking hooks, exit codes, and JSON output control

  • custom-slash-commands.md - Complete guide to creating and using custom slash commands

    • YAML frontmatter configuration with description, model, allowed-tools, and argument-hint
    • Argument handling with $ARGUMENTS and positional $1, $2 syntax
    • Bash integration and file references with ! and @ prefixes
    • Best practices for command organization and security
    • Examples: Bootstrap architecture docs, fix issues, generate tests, translate code

  • github-app-integration.md - GitHub app installation, authentication, and cost analysis

    • Two authentication methods: Subscription-based OAuth (Pro/Max plans) vs Direct API Key
    • Cost structure for GitHub Actions minutes and Claude API usage
    • Installation steps and workflow configuration examples
    • GitHub app capabilities: issue management, PR reviews, code modifications
    • Troubleshooting guides for authentication, permissions, and cost management
    • Migration paths between subscription and API key authentication

  • subagents-vs-skills.md - Comparison and integration patterns for task delegation

    • Sub-Agents: Separate AI assistants with isolated context, configurable models, restricted tool access
    • Skills: Modular capabilities that Claude auto-discovers contextually
    • Slash Commands: User-invoked prompts that expand to full instructions
    • Execution hierarchy: Sub-agents are “leaf nodes” (cannot call other agents/skills)
    • Commands and Skills can orchestrate multiple sub-agents and skills
    • Integration patterns for complex workflows and parallel processing

  • agent-cli-implementation.md - CLI to invoke agents from .claude/agents/

    • Agent file structure with YAML frontmatter
    • Three implementation approaches: direct CLI, SDK, shell wrapper
    • Package structure for packages/agent-cli/

  • plugins-marketplace.md - Plugin system and marketplace for sharing extensions

    • Plugin structure: plugin.json manifest, directory layout
    • Creating plugins: bundle commands, agents, MCP servers, hooks
    • Hosting marketplaces: marketplace.json format, GitHub/git/local sources
    • Installation: /plugin install and /plugin marketplace add commands

  • haiku-vs-sonnet-performance.md - Detailed model performance comparison and decision framework

    • Speed: Haiku 4.5 is 3-5x faster than Sonnet 4.5 with sub-200ms latency
    • Cost: Haiku at 5 vs Sonnet at 15 per million tokens (1/3 cost ratio)
    • Quality: Haiku achieves 90% of Sonnet’s performance on coding tasks
    • SWE-bench scores: Haiku 73.3% vs Sonnet 77.2% (3.9 percentage point gap)
    • Recommendation: Use Haiku for template-based, high-volume, speed-critical tasks; Sonnet for complex reasoning
    • Practical applications: Batch operations with Task subagents can run 10x faster with Haiku

  • ide-integration-programmatic-messaging.md - IDE integrations and programmatic message submission

    • JetBrains plugin (IntelliJ, WebStorm, PyCharm): keyboard shortcuts, diagnostics sharing, diff viewing
    • IDE plugin architecture: bridge to CLI terminal, not standalone API
    • Programmatic message submission via headless mode (-p flag), stdin piping, CLI automation
    • Context sharing: CLAUDE.md auto-loading, /ide command, file references
    • Current limitations: no direct API, stdin doesn’t pre-populate interactive TUI (feature request #6009)
    • Workarounds: custom IDE actions executing CLI, external scripts with hotkeys

  • disable-ctrl-d-exit.md - Preventing accidental exits from Ctrl+D

    • Shell-level IGNOREEOF configuration for bash/zsh to require multiple Ctrl+D presses
    • Alternative text deletion shortcuts (Delete, Ctrl+K, Ctrl+W)
    • Vim mode for modal editing to avoid Ctrl+D entirely
    • Technical explanation of EOF behavior and Node.js readline limitations
    • No built-in Claude Code option - relies on shell/terminal configuration

Key Findings & Recommendations

Architecture & Design Patterns

Command-Driven Workflows

  • Custom slash commands provide structured, reusable interfaces for automation
  • Support arguments, file references, Bash integration, and security controls
  • Best for repeatable, well-defined workflows

Task Delegation Strategies

  • Use Sub-Agents for isolated, specialized tasks (security audits, code reviews, test generation)
  • Use Skills for auto-discovered patterns and team conventions
  • Use Slash Commands for user-invoked orchestration
  • Commands and Skills can compose multiple sub-agents for complex workflows

Model Selection Framework

  • Haiku 4.5: 90% of Sonnet’s quality at 1/3 cost and 3-5x speed
    • Template-based operations (README generation, TOC creation, frontmatter updates)
    • Batch processing with Task subagents
    • High-throughput pipelines
    • Real-time interactions
  • Sonnet 4.5: Full quality for complex reasoning
    • Architectural decisions
    • Deep code analysis
    • Novel problem-solving
    • Critical bug analysis

Performance Metrics (Haiku 4.5 vs Sonnet 4.5)

MetricHaikuSonnetRatio
Speed3-5x fasterBaseline3-5x
LatencySub-200ms~600-1000ms3-5x better
Cost5 per 1M15 per 1M1/3
SWE-bench73.3%77.2%90% match
ThroughputHighMedium3-5x better

Authentication & Cost Management

GitHub Integration Options

  • Subscription-based OAuth (Pro/Max): Fixed monthly ($20-100), shared rate limits with web/desktop
  • Direct API Key: Pay-per-token, no rate limit windows
  • AWS Bedrock: GitHub OIDC integration
  • Google Vertex AI: Workload Identity Federation

Cost Optimization

  • Use subscription for predictable, light-to-moderate usage
  • Use API key for high-volume or bursty workloads
  • Configure max-turns and timeout-minutes in workflows
  • Monitor usage with /cost and /usage commands

Security Considerations

Custom Command Security

  • Always declare allowed-tools in frontmatter (e.g., Bash(git status:*))
  • Use specific command patterns to restrict access
  • Never expose sensitive information in version-controlled commands

GitHub App Permissions

  • Grant minimum necessary permissions (Contents, Issues, Pull Requests)
  • Use repository-specific installations when possible
  • Rotate tokens and API keys regularly
  • Monitor usage for unexpected activity

Directly Related (high relevance):

  • claude-code-agents - Agent development research and testing workflows (score: 90)
  • agents - AI agent patterns and communication protocols (score: 110)
  • claude-opus-4-5 - Claude Opus 4.5 deployment and usage strategies (score: 125)
  • factory-ai-droid - Factory.ai Droid compatibility with Claude Code configurations (score: 95)

Technology Ecosystem (shared technologies):

Reference Materials:

Quick Reference: When to Use What

Slash Commands ✅ Use When:

  • Creating repeatable workflows
  • Need structured arguments and help text
  • Combining multiple operations in sequence
  • Enforcing security via allowed-tools

Sub-Agents ✅ Use When:

  • Task requires isolated, specialized expertise
  • Need parallel processing of independent work
  • Want to restrict tool access for security
  • Building reusable AI personalities

Skills ✅ Use When:

  • Automating frequently repeated patterns
  • Encoding team conventions and standards
  • Need auto-discovery based on context
  • Building composable capability library

Haiku Model ✅ Use When:

  • Speed matters (sub-200ms latency required)
  • Processing high volumes
  • Budget is constrained
  • Task is template-based or well-structured
  • 90% quality is acceptable

Sonnet Model ✅ Use When:

  • Complex reasoning required
  • Quality is paramount
  • Architectural decisions involved
  • Deep code understanding needed
  • Nuanced contextual analysis required

Official Documentation:

GitHub Resources:

Pricing & Billing:

File Organization

claude-code/
├── README.md                                 # This file - Overview and quick reference
├── hooks.md                                  # Event-driven automation system
├── custom-slash-commands.md                  # Complete guide to slash command creation
├── github-app-integration.md                 # GitHub automation and authentication
├── haiku-vs-sonnet-performance.md            # Model performance benchmarks
├── subagents-vs-skills.md                    # Task delegation patterns and comparisons
├── ide-integration-programmatic-messaging.md # IDE integrations and CLI automation
├── disable-ctrl-d-exit.md                    # Preventing accidental CLI exits with Ctrl+D
├── agent-cli-implementation.md               # Agent CLI implementation guide
└── plugins-marketplace.md                    # Plugin system and marketplace

Last updated: 2025-12-11

Status: Comprehensive research completed with performance benchmarks, architectural patterns, and implementation guides.

Next steps: Monitor new Claude Code releases for feature updates; validate Haiku performance in production workflows.