@aladac/hu 0.1.0-a1 → 0.1.0-a2

package/CLAUDE.md

@@ -11,60 +11,84 @@ This is the `~/.claude` configuration directory containing custom slash commands
 - `commands/` - Slash command definitions (`.md` files that become `/command-name`)
   - `docs/` - Documentation management commands (`/docs:*`)
   - `plans/` - Planning commands (`/plans:*`)
-- `src/` - TypeScript source for the `honbu` CLI
+- `src/` - TypeScript source for the `hu` CLI
   - `commands/` - CLI subcommand implementations
-  - `lib/` - Shared utilities (fs, colors, html conversion)
+  - `lib/` - Shared utilities (fs, colors, html conversion, db, sync)
 - `doc/` - Reference documentation fetched from the web
 - `documents/` - Global documentation store (`~/.claude/documents/`)
+- `hooks/` - Hook scripts for Claude Code events
 - `plans/` - Saved implementation plans (PLAN.md files)
 - `plugins/` - Claude Code plugins
 - `settings.json` - Global permissions and plugin configuration
 
-## CLI Tool: honbu
+## CLI Tool: hu
 
 A unified CLI for Claude Code workflows. Install with:
 ```bash
 cd ~/.claude && npm install
 ```
 
-The `honbu` binary provides these subcommands:
+The `hu` binary provides these subcommands:
 
-### honbu docs
+### hu data
+Access Claude Code session data (requires SQLite database):
+```bash
+hu data sync                   # Sync Claude data to local database
+hu data sync -f                # Force full sync
+hu data config                 # Show current configuration
+hu data config -j              # JSON output
+hu data session list           # List sessions
+hu data session list -p <dir>  # Filter by project
+hu data stats                  # Show usage statistics
+hu data todos pending          # Show pending todos
+hu data search <query>         # Search messages
+hu data tools                  # Show tool usage statistics
+hu data errors                 # Extract errors from debug logs
+```
+
+### hu docs
 Documentation management:
 ```bash
-honbu docs list [location]     # List docs (project|global|all|repo)
-honbu docs list -j             # JSON output
-honbu docs check               # Check system document status in repo
-honbu docs scan [target]       # Scan docs for sync (shows staleness)
-honbu docs archive <file...>   # Archive docs to global store
+hu docs list [location]        # List docs (project|global|all|repo)
+hu docs list -j                # JSON output
+hu docs check                  # Check system document status in repo
+hu docs scan [target]          # Scan docs for sync (shows staleness)
+hu docs archive <file...>      # Archive docs to global store
 ```
 
-### honbu plans
+### hu plans
 Plan management:
 ```bash
-honbu plans list               # List saved plans
-honbu plans list -f            # Full content preview
-honbu plans clear              # Delete all plans (with confirmation)
-honbu plans clear -d           # Dry run
+hu plans list                  # List saved plans
+hu plans list -f               # Full content preview
+hu plans clear                 # Delete all plans (with confirmation)
+hu plans clear -d              # Dry run
 ```
 
-### honbu utils
+### hu utils
 Utility commands:
 ```bash
-honbu utils fetch-html <url>              # Fetch URL, convert to markdown
-honbu utils fetch-html <url> -c           # With extra cleaning
-honbu utils fetch-html <url> -s "article" # Target CSS selector
-honbu utils fetch-html <url> -o out.md    # Write to file
-
-honbu utils sync-checkboxes               # Clean TODO.md/PLAN.md
-honbu utils sync-checkboxes file.md       # Specific file
-honbu utils sync-checkboxes -d            # Dry run
+hu utils fetch-html <url>              # Fetch URL, convert to markdown
+hu utils fetch-html <url> -c           # With extra cleaning
+hu utils fetch-html <url> -s "article" # Target CSS selector
+hu utils fetch-html <url> -o out.md    # Write to file
+
+hu utils sync-checkboxes               # Clean TODO.md/PLAN.md
+hu utils sync-checkboxes file.md       # Specific file
+hu utils sync-checkboxes -d            # Dry run
 ```
 
-### honbu disk
+### hu disk
 Disk space analysis (macOS):
 ```bash
-honbu disk                     # Show disk usage summary
+hu disk                        # Show disk usage summary
+```
+
+### hu plugin
+Plugin management:
+```bash
+hu plugin init <name>          # Initialize a new plugin
+hu plugin install              # Install plugin hooks
 ```
 
 ## Slash Commands
@@ -88,10 +112,11 @@ honbu disk                     # Show disk usage summary
 ### Utilities
 - `/c` - Quick commit: adds all files, commits with timestamp message
 - `/disk` - Disk space analysis commands for macOS
-- `/bootstrap` - Bootstrap honbu if not installed
-- `/reinstall` - Reinstall honbu from source
+- `/bootstrap` - Bootstrap hu if not installed
+- `/reinstall` - Reinstall hu from source
 - `/check-name <name>` - Check package name availability across registries
 - `/replicate` - Diagnose a reported issue and identify code areas to investigate
+- `/warp` - Custom command
 
 ## System Documents (Off-Limits)
 
@@ -102,7 +127,7 @@ The `/docs:*` commands explicitly ignore these files:
 
 ## Documentation Workflow
 
-1. **Fetching**: `/docs:get` uses `honbu utils fetch-html` to grab web content, stores with YAML frontmatter containing source URL and fetch date
+1. **Fetching**: `/docs:get` uses `hu utils fetch-html` to grab web content, stores with YAML frontmatter containing source URL and fetch date
 2. **Manifests**: Project docs tracked in `./document-manifest.toml`, global in `~/.claude/documents/manifest.toml`
 3. **Syncing**: `/docs:sync` re-fetches sources, follows new reference links, updates frontmatter dates
 4. **Locations**:

package/HOOKS.md

@@ -0,0 +1,146 @@
+# Hooks + Data Integration
+
+Claude Code hooks that tap into local data stores for context-aware automation.
+
+## Installation
+
+### Prerequisites
+
+Install the `hu` CLI:
+
+```bash
+cd ~/.claude && npm install
+npm link  # or: npm install -g @aladac/hu
+```
+
+### Configure Claude Code Hooks
+
+Add to `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": ".*",
+        "hooks": [{ "type": "command", "command": "~/.claude/hooks/session-start.sh" }]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": ".*",
+        "hooks": [{ "type": "command", "command": "~/.claude/hooks/user-prompt-submit.sh" }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": ".*",
+        "hooks": [{ "type": "command", "command": "~/.claude/hooks/stop.sh" }]
+      }
+    ]
+  }
+}
+```
+
+### Configuration
+
+The `hu` CLI uses `~/.config/hu/settings.toml` for configuration:
+
+```toml
+[general]
+claude_dir = "~/.claude"    # Claude Code data directory
+database = "hu.db"          # SQLite database name
+
+[sync]
+auto_sync_interval = 300    # Seconds between auto-syncs (0 = manual)
+sync_on_start = true
+
+[hooks]
+enabled = true
+temp_dir = "/tmp"           # Temp files for hook data exchange
+temp_file_ttl = 3600        # Cleanup temp files after (seconds)
+
+[search]
+default_limit = 20
+show_snippets = true
+
+[output]
+default_format = "table"
+colors = true
+date_format = "%Y-%m-%d %H:%M"
+```
+
+## Features
+
+- **Session Context Loading** - On session start, automatically loads recent sessions, pending todos, and recently modified files for the current project. Provides continuity across sessions without manual context-setting.
+
+- **Similarity Search** - When you submit a prompt, searches past transcripts for similar prompts and solutions. Surfaces relevant prior work so you don't reinvent the wheel.
+
+- **Usage Statistics** - Aggregates token usage, costs, peak activity hours, and model distribution from stats cache. Helps track spending and identify usage patterns.
+
+- **Cross-Session Todo Sync** - Extracts incomplete todos from any session and makes them available globally. No more losing track of tasks when sessions end.
+
+- **File Modification Tracking** - Monitors which files get edited frequently across sessions. Flags "hot" files that might need refactoring or closer attention.
+
+- **Session Summarization** - On stop, extracts learnings and summaries from the session transcript. Builds a knowledge base of solved problems over time.
+
+- **Tool Usage Patterns** - Tracks which tools are used, how often, and in what contexts. Identifies automation opportunities and common workflows.
+
+## Data Sources
+
+| Source | Location | Contains |
+|--------|----------|----------|
+| Transcripts | `projects/{path}/{session}.jsonl` | Full message history, tool calls, costs |
+| History | `history.jsonl` | Session index with prompts |
+| Stats | `stats-cache.json` | Aggregated metrics |
+| Todos | `todos/{session}.json` | Task lists per session |
+| File History | `file-history/{session}/` | File version snapshots |
+| Plans | `plans/*.md` | Saved implementation plans |
+| Debug | `debug/{session}.txt` | Error logs, timing data |
+
+## Hook Events
+
+- `SessionStart` - Load context, show recent activity
+- `UserPromptSubmit` - Find similar past work
+- `PreToolUse` - Check file history before edits
+- `PostToolUse` - Track patterns, flag hot files
+- `Stop` - Summarize session, extract learnings
+- `SessionEnd` - Archive todos, update indexes
+
+## CLI Commands
+
+The `hu data` command provides access to Claude Code session data:
+
+```bash
+hu data sync              # Sync Claude Code data to SQLite
+hu data sync --quiet      # Quiet mode for hooks
+hu data config            # Show configuration
+hu data session list      # List sessions
+hu data session read <id> # Read session transcript
+hu data session current   # Show current session ($SESSION_ID)
+hu data stats             # Usage statistics
+hu data search <query>    # Full-text search
+hu data tools             # Tool usage patterns
+hu data todos list        # List all todos
+hu data todos pending     # Show pending todos
+hu data errors            # Extract errors from debug logs
+```
+
+All commands support `--json` for machine-readable output and `--output <path>` to write to a file.
+
+## Architecture
+
+The hooks use a temp-file approach for data exchange to avoid shell escaping issues:
+
+1. Hook receives JSON input via stdin
+2. Writes input to temp file for parsing
+3. Calls `hu data` commands with `--json --output` flags
+4. Reads results from temp files
+5. Builds response JSON and outputs to stdout
+6. Temp files are cleaned up after `temp_file_ttl` seconds
+
+This approach ensures safe handling of:
+- Unicode characters (emoji, CJK, RTL)
+- Special shell characters (`$`, backticks, quotes)
+- Multiline content and code blocks
+- Nested JSON structures

package/commands/reinstall.md

@@ -3,13 +3,16 @@ Reinstall hu from source.
 ## Command
 
 ```bash
+# Remove existing hu command if present (avoid conflicts)
+which hu &>/dev/null && npm unlink -g hu 2>/dev/null
 cd ~/.claude && npm install && npm link
 ```
 
 This will:
-1. Install/update dependencies from package.json
-2. Rebuild TypeScript via tsx
-3. Update global symlink for `hu` binary
+1. Remove any existing `hu` command to avoid conflicts
+2. Install/update dependencies from package.json
+3. Rebuild TypeScript via tsx
+4. Update global symlink for `hu` binary
 
 ## Verify
 

package/hooks/session-start.sh

@@ -0,0 +1,85 @@
+#!/bin/bash
+# Session Start Hook for hu data integration
+# Loads context from previous sessions and pending todos for the current project
+#
+# This hook is called when a new Claude Code session starts.
+# It syncs data and provides context about past sessions and pending tasks.
+#
+# Installation:
+# Add to ~/.claude/settings.json:
+# {
+#   "hooks": {
+#     "SessionStart": [
+#       {
+#         "matcher": ".*",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/session-start.sh" }]
+#       }
+#     ]
+#   }
+# }
+
+set -e
+
+# Read input from stdin to temp file
+INPUT_FILE=$(mktemp /tmp/hu-session-start-XXXXXX.json)
+cat > "$INPUT_FILE"
+
+# Extract project path from input
+PROJECT=$(jq -r '.cwd // empty' "$INPUT_FILE" 2>/dev/null || echo "")
+
+# Clean up input file
+rm -f "$INPUT_FILE"
+
+# Check if hu is available
+if ! command -v hu &> /dev/null; then
+    exit 0
+fi
+
+# Sync data (quick, uses interval from config)
+hu data sync --quiet 2>/dev/null || true
+
+# Get recent sessions for this project
+SESSIONS_FILE=$(mktemp /tmp/hu-sessions-XXXXXX.json)
+if [ -n "$PROJECT" ]; then
+    hu data session list --project "$PROJECT" --limit 5 --json > "$SESSIONS_FILE" 2>/dev/null || echo "[]" > "$SESSIONS_FILE"
+else
+    hu data session list --limit 5 --json > "$SESSIONS_FILE" 2>/dev/null || echo "[]" > "$SESSIONS_FILE"
+fi
+
+# Get pending todos
+TODOS_FILE=$(mktemp /tmp/hu-todos-XXXXXX.json)
+if [ -n "$PROJECT" ]; then
+    hu data todos pending --project "$PROJECT" --json > "$TODOS_FILE" 2>/dev/null || echo "[]" > "$TODOS_FILE"
+else
+    hu data todos pending --json > "$TODOS_FILE" 2>/dev/null || echo "[]" > "$TODOS_FILE"
+fi
+
+# Count sessions and todos
+SESSION_COUNT=$(jq 'length' "$SESSIONS_FILE" 2>/dev/null || echo "0")
+TODO_COUNT=$(jq 'length' "$TODOS_FILE" 2>/dev/null || echo "0")
+
+# Build context message
+CONTEXT=""
+
+if [ "$SESSION_COUNT" -gt 0 ]; then
+    CONTEXT="## Previous Sessions\\n\\n"
+    CONTEXT+=$(jq -r '.[] | "- Session \(.id[0:8]): \(.display // "No description") (\(.message_count) messages)"' "$SESSIONS_FILE" 2>/dev/null || echo "")
+    CONTEXT+="\\n\\n"
+fi
+
+if [ "$TODO_COUNT" -gt 0 ]; then
+    CONTEXT+="## Pending Tasks\\n\\n"
+    CONTEXT+=$(jq -r '.[] | "- [\(.status)] \(.content)"' "$TODOS_FILE" 2>/dev/null || echo "")
+fi
+
+# Clean up temp files
+rm -f "$SESSIONS_FILE" "$TODOS_FILE"
+
+# Output response if we have context
+if [ -n "$CONTEXT" ]; then
+    # Escape for JSON
+    CONTEXT_ESCAPED=$(echo -e "$CONTEXT" | jq -Rs .)
+    echo "{\"additionalContext\": $CONTEXT_ESCAPED}"
+else
+    echo "{}"
+fi

package/hooks/stop.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+# Stop Hook for hu data integration
+# Syncs session data when Claude Code stops
+#
+# This hook is called when a Claude Code session ends.
+# It ensures the session data is synced to the database.
+#
+# Installation:
+# Add to ~/.claude/settings.json:
+# {
+#   "hooks": {
+#     "Stop": [
+#       {
+#         "matcher": ".*",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/stop.sh" }]
+#       }
+#     ]
+#   }
+# }
+
+set -e
+
+# Read input from stdin to temp file
+INPUT_FILE=$(mktemp /tmp/hu-stop-XXXXXX.json)
+cat > "$INPUT_FILE"
+
+# Check if stop hook is already active (prevent recursion)
+STOP_HOOK_ACTIVE=$(jq -r '.stop_hook_active // false' "$INPUT_FILE" 2>/dev/null || echo "false")
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+    rm -f "$INPUT_FILE"
+    echo "{}"
+    exit 0
+fi
+
+# Extract session ID if available
+SESSION_ID=$(jq -r '.sessionId // empty' "$INPUT_FILE" 2>/dev/null || echo "")
+
+# Clean up input file
+rm -f "$INPUT_FILE"
+
+# Check if hu is available
+if ! command -v hu &> /dev/null; then
+    echo "{}"
+    exit 0
+fi
+
+# Force sync to capture this session's data
+hu data sync --quiet 2>/dev/null || true
+
+# Output empty response (no context needed on stop)
+echo "{}"

package/hooks/user-prompt-submit.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# User Prompt Submit Hook for hu data integration
+# Finds similar past work based on the user's prompt
+#
+# This hook is called when the user submits a prompt.
+# It searches for similar messages from past sessions.
+#
+# Installation:
+# Add to ~/.claude/settings.json:
+# {
+#   "hooks": {
+#     "UserPromptSubmit": [
+#       {
+#         "matcher": ".*",
+#         "hooks": [{ "type": "command", "command": "~/.claude/hooks/user-prompt-submit.sh" }]
+#       }
+#     ]
+#   }
+# }
+
+set -e
+
+# Read input from stdin to temp file
+INPUT_FILE=$(mktemp /tmp/hu-prompt-submit-XXXXXX.json)
+cat > "$INPUT_FILE"
+
+# Extract the user's prompt
+PROMPT=$(jq -r '.message.content // empty' "$INPUT_FILE" 2>/dev/null || echo "")
+
+# Clean up input file
+rm -f "$INPUT_FILE"
+
+# Skip if no prompt or prompt is too short
+if [ -z "$PROMPT" ] || [ ${#PROMPT} -lt 10 ]; then
+    echo "{}"
+    exit 0
+fi
+
+# Check if hu is available
+if ! command -v hu &> /dev/null; then
+    echo "{}"
+    exit 0
+fi
+
+# Extract first few words for search (avoid searching full long prompts)
+SEARCH_TERMS=$(echo "$PROMPT" | head -c 100 | tr -d '\n' | sed 's/[^a-zA-Z0-9 ]//g' | awk '{for(i=1;i<=NF && i<=5;i++) printf "%s ", $i}')
+
+# Skip if search terms are too generic
+if [ -z "$SEARCH_TERMS" ] || [ ${#SEARCH_TERMS} -lt 5 ]; then
+    echo "{}"
+    exit 0
+fi
+
+# Search for similar past messages
+RESULTS_FILE=$(mktemp /tmp/hu-search-XXXXXX.json)
+hu data search "$SEARCH_TERMS" --limit 3 --json > "$RESULTS_FILE" 2>/dev/null || echo "[]" > "$RESULTS_FILE"
+
+# Count results
+RESULT_COUNT=$(jq 'length' "$RESULTS_FILE" 2>/dev/null || echo "0")
+
+# Build context if we found relevant results
+if [ "$RESULT_COUNT" -gt 0 ]; then
+    CONTEXT="## Similar Past Work\\n\\nFound $RESULT_COUNT related messages from previous sessions:\\n\\n"
+    CONTEXT+=$(jq -r '.[] | "- [\(.role)] in session \(.session_id[0:8]): \(.content[0:100] | gsub("\n"; " "))..."' "$RESULTS_FILE" 2>/dev/null || echo "")
+    
+    # Escape for JSON
+    CONTEXT_ESCAPED=$(echo -e "$CONTEXT" | jq -Rs .)
+    echo "{\"additionalContext\": $CONTEXT_ESCAPED}"
+else
+    echo "{}"
+fi
+
+# Clean up
+rm -f "$RESULTS_FILE"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aladac/hu",
-  "version": "0.1.0-a1",
+  "version": "0.1.0-a2",
   "description": "CLI tools for Claude Code workflows",
   "type": "module",
   "bin": {
@@ -16,16 +16,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "better-sqlite3": "^12.6.0",
     "cheerio": "^1.1.2",
     "citty": "^0.1.6",
+    "smol-toml": "^1.6.0",
     "turndown": "^7.2.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^22.0.0",
     "@types/turndown": "^5.0.5",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^4.0.17"
   },
   "engines": {
     "node": ">=23.6.0"