@aladac/hu 0.1.0-a1 → 0.1.0-a2

package/HOOKS-DATA-INTEGRATION.md

@@ -1,457 +0,0 @@
-# Hooks + Data Integration Analysis
-
-How honbu hooks can tap into existing Claude Code data stores.
-
-## Available Data Sources
-
-### 1. Session Transcripts (`projects/{encoded-path}/{session}.jsonl`)
-
-**Format**: JSONL with message threading
-
-**Available Data**:
-```json
-{
-  "uuid": "msg-uuid",
-  "parentUuid": "parent-uuid",
-  "sessionId": "session-uuid",
-  "type": "user|assistant|summary",
-  "timestamp": "ISO-8601",
-  "cwd": "/working/directory",
-  "gitBranch": "feature-branch",
-  "message": {
-    "role": "user|assistant",
-    "content": "...|[{type:'tool_use',...}]",
-    "model": "claude-opus-4-5-20251101",
-    "usage": {
-      "input_tokens": 1234,
-      "output_tokens": 567,
-      "cache_read_input_tokens": 9000,
-      "cache_creation_input_tokens": 500
-    }
-  },
-  "costUSD": 0.0123,
-  "durationMs": 5000
-}
-```
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionStart` | Load recent messages, extract context |
-| `Stop` | Summarize session, extract learnings |
-| `UserPromptSubmit` | Find similar past prompts/solutions |
-| `PostToolUse` | Track tool patterns over time |
-
-**honbu commands**:
-```bash
-honbu session read <session-id>           # Parse JSONL
-honbu session search <query>              # Full-text search
-honbu session stats <session-id>          # Token/cost summary
-honbu session tools <session-id>          # List tool usage
-honbu session thread <session-id>         # Reconstruct thread
-honbu session export <session-id> [format] # Export markdown/json
-```
-
----
-
-### 2. History Index (`history.jsonl`)
-
-**Format**: JSONL session index
-
-**Available Data**:
-```json
-{
-  "display": "user prompt preview",
-  "pastedContents": {},
-  "timestamp": 1768082044191,
-  "project": "/Users/chi/myproject",
-  "sessionId": "session-uuid"
-}
-```
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionStart` | Show recent sessions for context |
-| `UserPromptSubmit` | Find similar past prompts |
-
-**honbu commands**:
-```bash
-honbu history list [--project <path>]     # List sessions
-honbu history recent [n]                  # Last N sessions
-honbu history search <query>              # Search prompts
-honbu history by-project                  # Group by project
-```
-
----
-
-### 3. Stats Cache (`stats-cache.json`)
-
-**Format**: JSON aggregate statistics
-
-**Available Data**:
-```json
-{
-  "totalSessions": 85,
-  "totalMessages": 13827,
-  "dailyActivity": [
-    {"date": "2026-01-12", "messageCount": 10168, "sessionCount": 48, "toolCallCount": 3560}
-  ],
-  "modelUsage": {
-    "claude-opus-4-5-20251101": {
-      "inputTokens": 233573,
-      "outputTokens": 1504031,
-      "cacheReadInputTokens": 518656034,
-      "costUSD": 0
-    }
-  },
-  "hourCounts": {"9": 9, "16": 11, "23": 16},
-  "longestSession": {"sessionId": "...", "duration": 56868623, "messageCount": 63}
-}
-```
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionStart` | Show daily stats, suggest break times |
-| `SessionEnd` | Update custom metrics |
-| `Stop` | Compare session to averages |
-
-**honbu commands**:
-```bash
-honbu stats show                          # Display stats
-honbu stats today                         # Today's activity
-honbu stats tokens [--by-model]           # Token usage
-honbu stats cost [--period <days>]        # Cost tracking
-honbu stats peak-hours                    # Activity patterns
-```
-
----
-
-### 4. Todos (`todos/{session-uuid}.json`)
-
-**Format**: JSON array
-
-**Available Data**:
-```json
-[
-  {
-    "content": "Task description",
-    "status": "pending|in_progress|completed",
-    "activeForm": "Doing the task"
-  }
-]
-```
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionStart` | Load incomplete todos from other sessions |
-| `Stop` | Archive completed, handoff incomplete |
-| `SessionEnd` | Sync todos to central tracker |
-
-**honbu commands**:
-```bash
-honbu todos list [--status <status>]      # List all todos
-honbu todos pending                       # Cross-session pending
-honbu todos handoff <from> <to>           # Transfer todos
-honbu todos cleanup                       # Remove completed
-```
-
----
-
-### 5. File History (`file-history/{session-uuid}/`)
-
-**Format**: File snapshots with version suffix
-
-**Structure**: `{hash}@v{n}` files containing previous versions
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `PreToolUse` (Edit/Write) | Check for recent edits to same file |
-| `PostToolUse` (Edit/Write) | Track file modification patterns |
-| `SessionStart` | Report files modified in previous session |
-
-**honbu commands**:
-```bash
-honbu file-history list <session-id>      # Files modified
-honbu file-history diff <file> [version]  # Show diff
-honbu file-history restore <file> <ver>   # Restore version
-honbu file-history hot-files [days]       # Most edited files
-```
-
----
-
-### 6. Plans (`plans/{name}.md`)
-
-**Format**: Markdown with structured content
-
-**Naming**: `{adjective}-{verb}-{noun}.md`
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionStart` | Check for related plans |
-| `UserPromptSubmit` | Match prompt to existing plans |
-| `PreCompact` | Preserve plan references |
-
-**honbu commands**:
-```bash
-honbu plans list                          # List all plans
-honbu plans search <query>                # Search plan content
-honbu plans related <topic>               # Find related plans
-```
-
----
-
-### 7. Debug Logs (`debug/{session-uuid}.txt`)
-
-**Format**: Timestamped log lines
-
-**Available Data**:
-- Permission changes
-- Plugin loading
-- MCP server status
-- LSP initialization
-- Tool execution timing
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionEnd` | Extract errors, warnings |
-| `Stop` | Check for repeated errors |
-
-**honbu commands**:
-```bash
-honbu debug errors <session-id>           # Extract errors
-honbu debug warnings <session-id>         # Extract warnings
-honbu debug timing <session-id>           # Performance metrics
-```
-
----
-
-### 8. Shell Snapshots (`shell-snapshots/snapshot-*.sh`)
-
-**Format**: Executable shell scripts
-
-**Contains**: Functions, aliases, environment from user's shell
-
-**Hook Integration**:
-| Hook | Use Case |
-|------|----------|
-| `SessionStart` | Detect shell environment changes |
-
----
-
-## Data Flow Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                        Hook Events                               │
-├─────────────────────────────────────────────────────────────────┤
-│  SessionStart    UserPromptSubmit    PreToolUse    PostToolUse  │
-│  Stop            SessionEnd          PreCompact    Notification │
-└────────┬────────────────┬─────────────────┬────────────────┬────┘
-         │                │                 │                │
-         ▼                ▼                 ▼                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      honbu hooks                               │
-├─────────────────────────────────────────────────────────────────┤
-│  • Receives hook input (JSON via stdin)                         │
-│  • Queries local data stores                                    │
-│  • Returns context/decisions (JSON via stdout)                  │
-└────────┬────────────────┬─────────────────┬────────────────┬────┘
-         │                │                 │                │
-         ▼                ▼                 ▼                ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                     Data Stores                                  │
-├──────────────┬──────────────┬──────────────┬───────────────────┤
-│ projects/    │ history.jsonl│ stats-cache  │ todos/            │
-│ (transcripts)│ (index)      │ (metrics)    │ (tasks)           │
-├──────────────┼──────────────┼──────────────┼───────────────────┤
-│ file-history/│ plans/       │ debug/       │ session-env/      │
-│ (versions)   │ (plans)      │ (logs)       │ (env vars)        │
-└──────────────┴──────────────┴──────────────┴───────────────────┘
-```
-
----
-
-## Implementation: honbu data Subcommand
-
-New subcommand to access all Claude Code data:
-
-```bash
-honbu data <subcommand>
-
-# Session data
-honbu data session list [--project <path>]
-honbu data session read <id> [--format json|md]
-honbu data session search <query>
-honbu data session current                    # From $SESSION_ID
-
-# Cross-session queries
-honbu data search <query>                     # Full-text all sessions
-honbu data tools [--tool <name>]              # Tool usage patterns
-honbu data files [--modified-by <session>]    # File access patterns
-honbu data errors [--recent <days>]           # Error patterns
-
-# Aggregates
-honbu data stats [--period <days>]
-honbu data cost [--by-model] [--by-project]
-honbu data activity [--hourly|--daily]
-```
-
----
-
-## Hook Implementation Examples
-
-### SessionStart: Load Context
-
-```bash
-#!/bin/bash
-# honbu hooks session-start startup
-
-SESSION_ID=$(jq -r '.session_id' < /dev/stdin)
-PROJECT=$(pwd)
-
-# Get recent activity for this project
-RECENT=$(honbu data session list --project "$PROJECT" --limit 3 --json)
-
-# Get pending todos from previous sessions
-PENDING=$(honbu data todos pending --project "$PROJECT" --json)
-
-# Get recently modified files
-FILES=$(honbu data files --project "$PROJECT" --recent 1d --json)
-
-# Build context
-cat << EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "SessionStart",
-    "additionalContext": "## Recent Context\n\nPrevious sessions: $(echo $RECENT | jq -r 'length')\nPending tasks: $(echo $PENDING | jq -r 'length')\nRecently modified: $(echo $FILES | jq -r 'length') files"
-  }
-}
-EOF
-```
-
-### UserPromptSubmit: Find Similar Past Work
-
-```bash
-#!/bin/bash
-# honbu hooks user-prompt-submit
-
-PROMPT=$(jq -r '.prompt' < /dev/stdin)
-
-# Search for similar past prompts/solutions
-SIMILAR=$(honbu data search "$PROMPT" --limit 3 --json)
-
-if [ "$(echo $SIMILAR | jq 'length')" -gt 0 ]; then
-  CONTEXT="Similar past work found:\n$(echo $SIMILAR | jq -r '.[].summary')"
-  cat << EOF
-{
-  "hookSpecificOutput": {
-    "hookEventName": "UserPromptSubmit",
-    "additionalContext": "$CONTEXT"
-  }
-}
-EOF
-else
-  echo '{}'
-fi
-```
-
-### Stop: Extract Learnings
-
-```bash
-#!/bin/bash
-# honbu hooks stop
-
-INPUT=$(cat)
-SESSION_ID=$(echo "$INPUT" | jq -r '.session_id')
-STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active')
-
-# Don't loop
-if [ "$STOP_ACTIVE" = "true" ]; then
-  echo '{"ok": true}'
-  exit 0
-fi
-
-# Extract session summary
-honbu data session summarize "$SESSION_ID" >> ~/.claude/knowledge/sessions.jsonl
-
-echo '{"ok": true}'
-```
-
-### PostToolUse: Track Patterns
-
-```bash
-#!/bin/bash  
-# honbu hooks post-tool-use file-modify
-
-INPUT=$(cat)
-TOOL=$(echo "$INPUT" | jq -r '.tool_name')
-FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path')
-SESSION=$(echo "$INPUT" | jq -r '.session_id')
-
-# Log file modification
-honbu data log file-modify \
-  --session "$SESSION" \
-  --file "$FILE" \
-  --tool "$TOOL"
-
-# Check if file is frequently modified
-HOT=$(honbu data files hot --file "$FILE" --json)
-if [ "$(echo $HOT | jq '.count')" -gt 10 ]; then
-  echo "{\"hookSpecificOutput\":{\"additionalContext\":\"Note: $FILE has been modified $(echo $HOT | jq '.count') times recently\"}}"
-fi
-```
-
----
-
-## Data Index for Fast Queries
-
-Build indexes on first run, update incrementally:
-
-```
-~/.claude/index/
-├── sessions.idx          # Session metadata index
-├── messages.fts          # Full-text search index  
-├── tools.idx             # Tool usage index
-├── files.idx             # File access index
-└── errors.idx            # Error pattern index
-```
-
-**honbu commands**:
-```bash
-honbu index build [--force]               # Build/rebuild indexes
-honbu index status                        # Index health
-honbu index update                        # Incremental update
-```
-
----
-
-## Priority Implementation
-
-### Phase 1: Read-Only Access
-- [ ] `honbu data session read`
-- [ ] `honbu data session list`
-- [ ] `honbu data stats`
-- [ ] `honbu data todos pending`
-
-### Phase 2: Search & Query
-- [ ] `honbu data search`
-- [ ] `honbu data tools`
-- [ ] `honbu data files`
-- [ ] Index building
-
-### Phase 3: Hook Integration
-- [ ] SessionStart context loader
-- [ ] UserPromptSubmit similarity search
-- [ ] Stop summary extractor
-- [ ] PostToolUse pattern tracker
-
-### Phase 4: Knowledge System
-- [ ] Cross-session learning
-- [ ] Pattern recognition
-- [ ] Predictive suggestions