---

IDENTITY

title: "TICKET_052: Hook Package Build + Install (Mac + Hetzner)"
type: ticket
subtype: execution
purpose: "Build the struxio-bus-cc-hooks package and install on Mac Studio and Hetzner for Claude Code lifecycle event capture."

GOVERNANCE

status: ready
priority: P1
sprint: S001_base_and_mvp1
assignee: "Claude Code CLI (Mac terminal for build, both terminals for install)"
estimated_hours: 1.5
depends_on: [TICKET_049]
blocks: [TICKET_053]
last_updated: "2026-03-21 23:00"
blueprint: "BLUEPRINT_Bus_MCP_Server_v1.md Section 5"

TICKET_052: Hook Package Build + Install

Objective

Build the struxio-bus-cc-hooks Node.js package that captures Claude Code lifecycle events (SessionStart, Stop, TaskCompleted, TeammateIdle, PreCompact, SessionEnd) and publishes them to the Bus MCP Server. Install on both Mac Studio and Hetzner.

Context

• Full spec: BLUEPRINT Section 5
• 8 hook events for MVP (see Section 5.1)
• Command hooks preferred over HTTP hooks (explicit exit codes, spool on failure)
• Offline resilience: local spool at /var/lib/struxio-bus/spool/*.jsonl
• Git is the sync layer. Build on Mac, push to GitHub, pull on Hetzner.

Execution Steps

Step 1: Create Package (Mac CLI)

mkdir -p /opt/struxio/struxio-bus-cc-hooks
cd /opt/struxio/struxio-bus-cc-hooks
npm init -y
npm install dotenv node-fetch
npm install -D typescript @types/node tsx

Step 2: Implement bus_publish.ts

Key behaviors per event:

• SessionStart → bus.presence_heartbeat + bus.send_message(lifecycle:session_start)
• Stop → bus.send_message(lifecycle:response_completed, body=summary)
• TaskCompleted → bus.send_message(lifecycle:task_completed, body=summary)
• TeammateIdle → bus.poll(topic_prefix="task:") → if task found, output to stdout
• PreCompact → bus.send_message(lifecycle:precompact, body=state_snapshot)
• SessionEnd → bus.send_message(lifecycle:session_end)
• SubagentStart / SubagentStop → bus.send_message(lifecycle:subagent_*)

Step 3: Implement spool.ts

• appendToSpool(event): write JSONL line to /var/lib/struxio-bus/spool/
• flushSpool(): retry all with exponential backoff (base 1s, max 60s, jitter)

Step 4: Build + Git push (Mac CLI)

npm run build  # tsc → dist/
git init
cat > .gitignore << 'GITIGNORE'
node_modules/
.env
GITIGNORE
git add -A
git commit -m "feat: TICKET_052 — Hook package for Bus MCP Server"
git remote add origin git@github.com:STRUXIO/struxio-bus-cc-hooks.git
git push -u origin main

Step 5: Install on Mac

sudo mkdir -p /opt/struxio-bus/hooks
sudo cp dist/bus_publish.js /opt/struxio-bus/hooks/
sudo mkdir -p /var/lib/struxio-bus/spool

# Create env file
sudo tee /opt/struxio-bus/.env << 'EOF'
STRUXIO_BUS_URL=https://bus.struxio.ai
STRUXIO_BUS_TOKEN=<B0_MAC_CLI_TOKEN>
STRUXIO_ACTOR=B0_MAC_CLI
EOF

# Merge hook config into ~/.claude/settings.json
# See BLUEPRINT Section 5.2 for the exact JSON

Step 6: Install on Hetzner (Hetzner CLI)

# Pull from GitHub (Git is the sync layer — never rsync):
cd /opt/struxio
git clone git@github.com:STRUXIO/struxio-bus-cc-hooks.git
cd struxio-bus-cc-hooks
npm ci

sudo mkdir -p /opt/struxio-bus/hooks
sudo cp dist/bus_publish.js /opt/struxio-bus/hooks/
sudo mkdir -p /var/lib/struxio-bus/spool

# Create env for lead agent
sudo tee /opt/struxio-bus/.env << 'EOF'
STRUXIO_BUS_URL=https://bus.struxio.ai
STRUXIO_BUS_TOKEN=<HETZNER_LEAD_TOKEN>
STRUXIO_ACTOR=HETZNER_LEAD_1
EOF

# Merge hook config into Claude Code settings

Step 7: Test Hook Fire

# On Mac: start a Claude Code session
claude
# Verify SessionStart event appears in bus:
curl -H "Authorization: Bearer <B0_TOKEN>" \
  -X POST https://bus.struxio.ai/mcp \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"bus.poll","arguments":{"actor":"B0","cursor":0}},"id":1}'

Acceptance Criteria

• Package builds cleanly: npm run build succeeds
• Code pushed to GitHub: git@github.com:STRUXIO/struxio-bus-cc-hooks.git
• Mac install: /opt/struxio-bus/hooks/bus_publish.js exists
• Hetzner install: cloned from GitHub, /opt/struxio-bus/hooks/bus_publish.js exists
• ~/.claude/settings.json has hook entries for SessionStart, Stop, TaskCompleted, SessionEnd, TeammateIdle, PreCompact
• Starting Claude Code session produces SessionStart event in bus
• Completing a task produces TaskCompleted event in bus
• Spool works: disconnect bus, fire hook, reconnect, verify event appears

Rollback

Remove hook entries from ~/.claude/settings.json. Claude Code works normally without hooks.

---

STRUXIO.ai // Confidential & Proprietary // © 2026