@aladac/hu 0.1.0-a1 → 0.1.0-a3

package/CLAUDE.md

@@ -2,6 +2,16 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Important Guidelines
+
+**Before implementing new features**: Always check if Claude Code already has a built-in feature for the requested functionality:
+1. Check CLI help: `claude --help`
+2. Check interactive commands: `/help` within a session
+3. Search the web for "Claude Code [feature name]" to find recent additions
+4. Check official docs at docs.anthropic.com
+
+Don't duplicate existing capabilities.
+
 ## Overview
 
 This is the `~/.claude` configuration directory containing custom slash commands, CLI tools, and documentation management workflows for Claude Code.
@@ -11,60 +21,174 @@ 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
+  - `claude/` - Claude Code reference commands (`/claude:*`)
+- `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 data pricing                # Show pricing analysis
+```
+
+### 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 plist <file>                  # Read plist as colorized JSON
+hu utils plist com.apple.finder        # Read app preferences by bundle ID
+hu utils plist -l                      # List available preference plists
+hu utils plist -s <pattern>            # Search for plists by name
+hu utils plist <file> -k <key>         # Extract specific key (dot notation)
+hu utils plist <file> -r               # Output raw JSON without colors
+
+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                        # Full disk inventory
+hu disk overview               # APFS volume usage
+hu disk home                   # Home directory breakdown
+hu disk library                # ~/Library breakdown
+hu disk hogs                   # Check common space hogs
+hu disk models                 # List AI models
+hu disk cleanup                # Cleanup suggestions
+
+hu disk known                  # Scan all known space hogs with cleanup commands
+hu disk known dev-tools        # Filter by category (ai-models, dev-tools, apps, caches, system, media)
+hu disk known -m 1G            # Only show items >= 1GB
+hu disk known -j               # JSON output
+hu disk list-known             # List all known hog definitions
+hu disk list-known ai-models   # List definitions for category
+```
+
+### hu services
+Services and startup items management (macOS):
+```bash
+hu services summary            # Overview of all services
+hu services brew list          # List Homebrew services (-r for running only)
+hu services brew start <name>  # Start a brew service
+hu services brew stop <name>   # Stop a brew service
+hu services brew restart <name> # Restart a brew service
+hu services login              # List login items and user launch agents
+hu services launch list        # List launch agents/daemons (-t agent/daemon, -s user/system)
+hu services launch load <name> # Load (enable) a launch agent
+hu services launch unload <name> # Unload (disable) a launch agent
+```
+
+### hu gh
+GitHub integration:
+```bash
+hu gh config                   # Show GitHub configuration
+hu gh prs                      # List pull requests
+hu gh prs -s "search term"     # Search PRs
+hu gh runs                     # List workflow runs
+hu gh open <pr-number>         # Open PR in browser
+```
+
+### hu jira
+Jira integration:
+```bash
+hu jira auth                   # Authenticate with Jira via OAuth 2.0
+hu jira config                 # Show Jira configuration
+hu jira sprint                 # Show current sprint info
+hu jira tickets                # List assigned tickets (current sprint)
+hu jira search <query>         # Search tickets
+hu jira show <ticket>          # Show ticket details
+hu jira branch <ticket>        # Create git branch from ticket
+hu jira open <ticket>          # Open ticket in browser
+hu jira check                  # Find sprint tickets without descriptions
+```
+
+### hu settings
+Claude Code settings management:
+```bash
+hu settings show               # Show settings from all scopes
+hu settings edit               # Edit settings file in $EDITOR
+hu settings managed            # View/edit managed settings (highest priority)
+hu settings allow <pattern>    # Add a permission rule
+hu settings path               # Show paths to settings files
+```
+
+### hu plugin
+Plugin management:
+```bash
+hu plugin init <name>          # Initialize a new plugin
+hu plugin install              # Install plugin hooks
+```
+
+### hu bump
+Version bumping with configurable patterns (auto-detects format from git tags):
+```bash
+hu bump run                    # Bump prerelease (0.1.0-a1 -> 0.1.0-a2)
+hu bump run patch              # Bump patch (0.1.0-a2 -> 0.1.1-a1)
+hu bump run minor              # Bump minor (0.1.0-a2 -> 0.2.0-a1)
+hu bump run major              # Bump major (0.1.0-a2 -> 1.0.0-a1)
+hu bump run -p pre             # Use -preN pattern instead of -aN
+hu bump run -p beta            # Use -betaN pattern
+hu bump run -p rc              # Use -rcN pattern
+hu bump run -p none            # No prerelease suffix (0.1.0)
+hu bump run -t ""              # No tag prefix (default: "v")
+hu bump run --no-tag           # Skip git tagging
+hu bump run --no-push          # Skip git push
+hu bump run -d                 # Dry run
+
+hu bump detect                 # Show detected version format
+hu bump detect -j              # JSON output
 ```
 
 ## Slash Commands
@@ -85,11 +209,17 @@ honbu disk                     # Show disk usage summary
 - `/plans:sync` - Sync TODO.md and PLAN.md progress
 - `/plans:clear` - Delete all saved plans
 
+### Claude Code Reference (`/claude:*`)
+- `/claude:reference [topic]` - Load Claude Code CLI reference documentation
+
 ### Utilities
 - `/c` - Quick commit: adds all files, commits with timestamp message
+- `/bump [type]` - Bump package version (prerelease/patch/minor/major)
+- `/publish` - Publish package to npm registry
 - `/disk` - Disk space analysis commands for macOS
-- `/bootstrap` - Bootstrap honbu if not installed
-- `/reinstall` - Reinstall honbu from source
+- `/pricing` - Show pricing analysis and competitor comparison
+- `/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
 
@@ -102,7 +232,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/bump.md

@@ -0,0 +1,30 @@
+Bump package version. Auto-detects format from git tags.
+
+## Arguments
+
+$ARGUMENTS - bump type: `prerelease` (default), `patch`, `minor`, `major`
+
+## Usage
+
+```bash
+hu bump run $ARGUMENTS
+```
+
+## Options
+
+- `-p/--pattern` - prerelease pattern: `alpha` (a1), `pre` (pre1), `beta` (beta1), `rc` (rc1), `none`
+- `-t/--tag-prefix` - git tag prefix (default: "v", use "" for none)
+- `--no-tag` - skip git tagging
+- `--no-push` - skip git push
+- `--no-install` - skip npm install && npm link
+- `-d/--dry-run` - preview changes without executing
+
+## Examples
+
+- `/bump` - bump prerelease (0.1.0-a1 -> 0.1.0-a2)
+- `/bump patch` - bump patch (0.1.0-a2 -> 0.1.1-a1)
+- `/bump minor` - bump minor version
+- `/bump major` - bump major version
+- `/bump -d` - dry run to preview
+
+Run the bump now.

package/commands/claude/reference.md

@@ -0,0 +1,42 @@
+Load Claude Code CLI reference documentation for implementation guidance.
+
+## Reference Documentation
+
+The following documentation files in `doc/cli/` provide comprehensive reference for Claude Code implementation:
+
+| File | Content |
+|------|---------|
+| `settings.md` | settings.json format, scopes, permissions syntax |
+| `hooks.md` | Hooks reference (events, matchers, configuration) |
+| `tutorial.md` | Hooks getting started guide |
+| `plugins.md` | Plugin system reference |
+| `iam.md` | Identity, authentication, access management |
+| `capabilities.md` | Tool capabilities |
+| `structure.md` | Directory structure conventions |
+| `sdk.md` | SDK protocols |
+| `overview.md` | General overview |
+
+## Usage
+
+When the user invokes `/claude:reference`, read the relevant documentation files from `doc/cli/` based on what they're trying to implement:
+
+- **Settings/permissions**: Read `doc/cli/settings.md`
+- **Hooks**: Read `doc/cli/hooks.md` and `doc/cli/tutorial.md`
+- **Plugins**: Read `doc/cli/plugins.md`
+- **Authentication**: Read `doc/cli/iam.md`
+- **General questions**: Read `doc/cli/overview.md`
+
+If no specific topic is mentioned, provide a summary of available documentation and ask what aspect they need help with.
+
+## Example
+
+```
+User: /claude:reference settings permissions
+Action: Read doc/cli/settings.md, focus on permissions section
+
+User: /claude:reference hooks
+Action: Read doc/cli/hooks.md and doc/cli/tutorial.md
+
+User: /claude:reference
+Action: List available topics and ask for clarification
+```

package/commands/pricing.md

@@ -0,0 +1,16 @@
+Show pricing analysis and competitor comparison.
+
+Run `hu data pricing` to show:
+- Your subscription cost vs API equivalent cost
+- Break-even analysis for Max tiers
+- Competitor pricing comparison
+
+Options:
+- `-s, --subscription` - Your Claude subscription (free, pro, max5x, max20x)
+- `-j, --json` - Output as JSON
+
+```bash
+hu data pricing
+hu data pricing -s pro
+hu data pricing -j
+```

package/commands/publish.md

@@ -0,0 +1,20 @@
+Publish package to npm registry.
+
+## Command
+
+```bash
+npm publish --access public --tag alpha
+```
+
+This publishes the package with:
+- `--access public` - makes the scoped package publicly accessible
+- `--tag alpha` - tags as alpha release (required for prerelease versions)
+
+## Before Publishing
+
+Ensure you have:
+1. Bumped the version (`/bump` or `hu bump run`)
+2. Committed and pushed all changes
+3. Logged into npm (`npm login`)
+
+Run the publish now.

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