claudehq 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# Claude HQ
+
+A real-time command center for all your Claude Code sessions.
+
+## Features
+
+- **Session Discovery**: Automatically discovers all running Claude Code sessions
+- **Real-Time Activity**: Live stream of tool usage, prompts, and responses
+- **Task Management**: View tasks organized by status (Pending, In Progress, Completed)
+- **Linear-Inspired UI**: Clean, modern interface with dark/light themes
+- **Zero Config**: One command setup with automatic hook installation
+
+## Quick Start
+
+```bash
+# Install hooks (one time)
+npx claudehq setup
+
+# Start the dashboard
+npx claudehq
+```
+
+Open **http://localhost:3456** - done!
+
+## Requirements
+
+- **Node.js** 18+
+- **jq** - `brew install jq` (macOS) or `apt install jq` (Linux)
+
+## Commands
+
+```bash
+npx claudehq           # Start server
+npx claudehq setup     # Install Claude Code hooks
+npx claudehq status    # Check installation
+npx claudehq uninstall # Remove hooks
+```
+
+Or install globally:
+
+```bash
+npm i -g claudehq
+chq setup
+chq
+```
+
+## How It Works
+
+```
+Claude Code  ──▶  Hook Script  ──▶  Events File
+                      │                  │
+                      ▼                  ▼
+                  ┌─────────────────────────┐
+                  │      Claude HQ Server   │
+                  └───────────┬─────────────┘
+                              │ SSE
+                              ▼
+                  ┌─────────────────────────┐
+                  │     Web Dashboard       │
+                  │  • Sessions & Status    │
+                  │  • Task Board           │
+                  │  • Live Activity Feed   │
+                  └─────────────────────────┘
+```
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3456` | Server port |
+| `TASKS_BOARD_DATA_DIR` | `~/.claude/tasks-board` | Data directory |
+
+## Troubleshooting
+
+```bash
+# Check status
+npx claudehq status
+
+# Test hook manually
+echo '{"hook_event_name":"PreToolUse","session_id":"test"}' | ~/.claude/hooks/tasks-board-hook.sh
+
+# View events
+tail ~/.claude/tasks-board/events.jsonl
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+const { program } = require('commander');
+const path = require('path');
+const { version } = require('../package.json');
+
+program
+  .name('claudehq')
+  .description('Claude HQ - A beautiful command center for Claude Code')
+  .version(version);
+
+program
+  .command('start')
+  .description('Start the tasks board server')
+  .option('-p, --port <port>', 'Port to run on', '3456')
+  .option('--no-open', 'Don\'t open browser automatically')
+  .action((options) => {
+    process.env.PORT = options.port;
+    process.env.NO_OPEN = options.open ? '' : '1';
+    require('../lib/server.js');
+  });
+
+program
+  .command('setup')
+  .description('Install Claude Code hooks (run this first!)')
+  .option('--force', 'Overwrite existing hook script')
+  .action(async (options) => {
+    const setup = require('../scripts/setup.js');
+    await setup.install(options);
+  });
+
+program
+  .command('uninstall')
+  .description('Remove Claude Code hooks')
+  .action(async () => {
+    const setup = require('../scripts/setup.js');
+    await setup.uninstall();
+  });
+
+program
+  .command('status')
+  .description('Check if hooks are installed and server is running')
+  .action(async () => {
+    const setup = require('../scripts/setup.js');
+    await setup.status();
+  });
+
+// Default command is start
+program
+  .action(() => {
+    // If no command specified, run start
+    process.env.PORT = process.env.PORT || '3456';
+    require('../lib/server.js');
+  });
+
+program.parse();

package/hooks/settings.example.json

@@ -0,0 +1,58 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/tasks-board-hook.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/tasks-board-hook.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/tasks-board-hook.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/tasks-board-hook.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/tasks-board-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/tasks-board-hook.sh

@@ -0,0 +1,166 @@
+#!/bin/bash
+# tasks-board-hook.sh - Captures Claude Code events for Tasks Board
+#
+# Installation:
+# 1. Copy this file to ~/.claude/hooks/tasks-board-hook.sh
+# 2. Make it executable: chmod +x ~/.claude/hooks/tasks-board-hook.sh
+# 3. Add hooks to ~/.claude/settings.json (see README)
+#
+# Environment variables:
+# - TASKS_BOARD_DATA_DIR: Directory for events.jsonl (default: ~/.claude/tasks-board)
+# - TASKS_BOARD_SERVER: Server URL for instant delivery (default: http://localhost:3456)
+# - TASKS_BOARD_NOTIFY: Enable HTTP notification (default: true)
+
+set -e
+
+# Configuration
+DATA_DIR="${TASKS_BOARD_DATA_DIR:-$HOME/.claude/tasks-board}"
+EVENTS_FILE="${DATA_DIR}/events.jsonl"
+SERVER_URL="${TASKS_BOARD_SERVER:-http://localhost:3456}"
+ENABLE_NOTIFY="${TASKS_BOARD_NOTIFY:-true}"
+
+# Ensure data directory exists
+mkdir -p "$(dirname "$EVENTS_FILE")"
+
+# PATH setup for tools (jq, curl)
+KNOWN_PATHS=("/opt/homebrew/bin" "/usr/local/bin" "$HOME/.local/bin" "/usr/bin" "/bin")
+for dir in "${KNOWN_PATHS[@]}"; do
+  [ -d "$dir" ] && export PATH="$dir:$PATH"
+done
+
+# Find jq (required)
+JQ=$(command -v jq 2>/dev/null) || {
+  echo "tasks-board-hook: ERROR - jq not found" >&2
+  exit 1
+}
+
+# Find curl (optional)
+CURL=$(command -v curl 2>/dev/null) || CURL=""
+
+# Read input from stdin
+input=$(cat)
+
+# Extract common fields
+hook_event_name=$("$JQ" -r '.hook_event_name // "unknown"' <<< "$input")
+session_id=$("$JQ" -r '.session_id // "unknown"' <<< "$input")
+cwd=$("$JQ" -r '.cwd // ""' <<< "$input")
+
+# Generate timestamp (cross-platform)
+if [[ "$OSTYPE" == "darwin"* ]]; then
+  timestamp=$(perl -MTime::HiRes=time -e 'printf "%.0f", time * 1000' 2>/dev/null || echo $(($(date +%s) * 1000)))
+else
+  timestamp=$(($(date +%s) * 1000 + 10#$(date +%N | cut -c1-3)))
+fi
+
+event_id="${session_id}-${timestamp}-${RANDOM}"
+
+# Map event names to types
+case "$hook_event_name" in
+  PreToolUse)       event_type="pre_tool_use" ;;
+  PostToolUse)      event_type="post_tool_use" ;;
+  Stop)             event_type="stop" ;;
+  SubagentStop)     event_type="subagent_stop" ;;
+  SessionStart)     event_type="session_start" ;;
+  SessionEnd)       event_type="session_end" ;;
+  UserPromptSubmit) event_type="user_prompt_submit" ;;
+  Notification)     event_type="notification" ;;
+  PreCompact)       event_type="pre_compact" ;;
+  *)                event_type="unknown" ;;
+esac
+
+# Build event JSON based on type
+case "$event_type" in
+  pre_tool_use)
+    tool_name=$("$JQ" -r '.tool_name // ""' <<< "$input")
+    tool_input=$("$JQ" -c '.tool_input // {}' <<< "$input")
+    tool_use_id=$("$JQ" -r '.tool_use_id // ""' <<< "$input")
+    event=$("$JQ" -n -c \
+      --arg id "$event_id" \
+      --argjson ts "$timestamp" \
+      --arg type "$event_type" \
+      --arg sid "$session_id" \
+      --arg cwd "$cwd" \
+      --arg tool "$tool_name" \
+      --argjson input "$tool_input" \
+      --arg tuid "$tool_use_id" \
+      '{id:$id,timestamp:$ts,type:$type,sessionId:$sid,cwd:$cwd,tool:$tool,toolInput:$input,toolUseId:$tuid}')
+    ;;
+  post_tool_use)
+    tool_name=$("$JQ" -r '.tool_name // ""' <<< "$input")
+    tool_input=$("$JQ" -c '.tool_input // {}' <<< "$input")
+    tool_use_id=$("$JQ" -r '.tool_use_id // ""' <<< "$input")
+    # Truncate tool response to avoid huge events
+    tool_response=$("$JQ" -c 'if .tool_response | type == "string" and (. | length) > 500 then .tool_response[:500] + "..." else .tool_response // null end' <<< "$input")
+    event=$("$JQ" -n -c \
+      --arg id "$event_id" \
+      --argjson ts "$timestamp" \
+      --arg type "$event_type" \
+      --arg sid "$session_id" \
+      --arg cwd "$cwd" \
+      --arg tool "$tool_name" \
+      --argjson input "$tool_input" \
+      --argjson response "$tool_response" \
+      --arg tuid "$tool_use_id" \
+      --argjson success true \
+      '{id:$id,timestamp:$ts,type:$type,sessionId:$sid,cwd:$cwd,tool:$tool,toolInput:$input,toolResponse:$response,toolUseId:$tuid,success:$success}')
+    ;;
+  stop)
+    # Truncate response text
+    response=$("$JQ" -r 'if .response | type == "string" and (. | length) > 1000 then .response[:1000] + "..." else .response // "" end' <<< "$input")
+    event=$("$JQ" -n -c \
+      --arg id "$event_id" \
+      --argjson ts "$timestamp" \
+      --arg type "$event_type" \
+      --arg sid "$session_id" \
+      --arg cwd "$cwd" \
+      --arg response "$response" \
+      '{id:$id,timestamp:$ts,type:$type,sessionId:$sid,cwd:$cwd,response:$response}')
+    ;;
+  user_prompt_submit)
+    # Truncate prompt text
+    prompt=$("$JQ" -r 'if .prompt | type == "string" and (. | length) > 500 then .prompt[:500] + "..." else .prompt // "" end' <<< "$input")
+    event=$("$JQ" -n -c \
+      --arg id "$event_id" \
+      --argjson ts "$timestamp" \
+      --arg type "$event_type" \
+      --arg sid "$session_id" \
+      --arg cwd "$cwd" \
+      --arg prompt "$prompt" \
+      '{id:$id,timestamp:$ts,type:$type,sessionId:$sid,cwd:$cwd,prompt:$prompt}')
+    ;;
+  subagent_stop)
+    agent_id=$("$JQ" -r '.agent_id // ""' <<< "$input")
+    event=$("$JQ" -n -c \
+      --arg id "$event_id" \
+      --argjson ts "$timestamp" \
+      --arg type "$event_type" \
+      --arg sid "$session_id" \
+      --arg cwd "$cwd" \
+      --arg aid "$agent_id" \
+      '{id:$id,timestamp:$ts,type:$type,sessionId:$sid,cwd:$cwd,agentId:$aid}')
+    ;;
+  *)
+    event=$("$JQ" -n -c \
+      --arg id "$event_id" \
+      --argjson ts "$timestamp" \
+      --arg type "$event_type" \
+      --arg sid "$session_id" \
+      --arg cwd "$cwd" \
+      '{id:$id,timestamp:$ts,type:$type,sessionId:$sid,cwd:$cwd}')
+    ;;
+esac
+
+# Append to JSONL file
+echo "$event" >> "$EVENTS_FILE"
+
+# Notify server (fire and forget)
+if [ "$ENABLE_NOTIFY" = "true" ] && [ -n "$CURL" ]; then
+  "$CURL" -s -X POST "${SERVER_URL}/api/claude-events" \
+    -H "Content-Type: application/json" \
+    -d "$event" \
+    --connect-timeout 1 \
+    --max-time 2 \
+    >/dev/null 2>&1 &
+fi
+
+exit 0