claude-ns-hub 0.3.2

Personal AI project management hub — North Star milestone tracking, live Claude sessions, CTX context alignment.

claude-ns-hub

The personal AI project hub that runs while you work. North Star milestone tracking · live Claude exec sessions · entity corpus browser · mobile-ready terminal.

One command. Your whole AI workflow, visible from any device.

Why you need this

While Claude Code runs your tasks autonomously, you're flying blind — no idea what it just did, which session is live, or whether it's stuck. claude-ns-hub fixes that:

• See everything live: exec sessions, session IDs, idle/busy state — on your phone while you're away
• Queue work without interrupting Claude: tap a stone, queue it, it runs on next idle
• Resume any session: ↻ button resumes exact conversation context, never lose work
• One install, zero config: auto-discovers projects, spawns entity corpus, exposes to Tailscale

The engineers shipping the most with Claude Code are the ones who can monitor, queue, and intervene — without context-switching.

Prerequisites

• Python 3.10+
• Claude Code CLI installed and authenticated (claude --version)
• tmux installed (brew install tmux / apt install tmux)
• Tailscale (optional, for remote access)

Install (60 seconds)

pip install claude-ns-hub
hub                          # starts immediately on http://localhost:9001
# → All features auto-active: North Star, exec sessions, entity corpus,
#   Tailscale port-expose, anonymous usage telemetry (opt-out below).

That's it — no config file, no env vars, no separate daemon. Open the printed URL in any browser (phone or laptop, via Tailscale) and you're in.

Telemetry & privacy

The hub sends one anonymized hub_start event on startup (fields: ts, event, install_id=sha256(hostname)[:16], version, os). No PII, no code, no stone text is transmitted. Disable any time:

curl -X POST http://localhost:9001/api/hub/consent \
  -H 'Content-Type: application/json' \
  -d '{"data_collection": false}'

Quick start (manual install)

# 1. Start the hub
claude-ns-hub
# Hub starts at http://<your-ip>:9001
# North Star · CTX · Corpus · Market — all tabs, live

# 2. Inject the NS Hub protocol into your global Claude config (run once)
hub install-global
# Writes the stone lifecycle protocol to ~/.claude/CLAUDE.md
# Without this, exec sessions won't know how to update stone status

# 3. Add your first project
# In the hub UI: North Star tab → "+ node" button
# Set the project name and repo_path to your local project directory

# 4. Queue a stone and dispatch
# Click a project card → "+ milestone" → type your task
# Click "live" to start an exec session — Claude Code picks up the stone automatically

Exec session setup

The hub launches Claude Code in a tmux session named claude-exec-<PROJECT>. For this to work on a new machine:

# Verify Claude Code is authenticated
claude --version

# Install hub hooks into Claude Code's global settings (run once per machine)
hub install-global

# The hub will auto-create tmux sessions when you dispatch work
# Monitor live progress in the "session" pane of any project card

What you get

Feature	What it does
North Star swimlane	Visualize all projects + milestones on one screen
Live exec sessions	See claude-exec-MOAT running, its session ID, busy/idle state
Mobile terminal	⌨_ button attaches browser terminal to the running Claude session — type from your phone
Session resume	↻ rows resume exact prior conversation; ✦ starts fresh — your choice per stone
Entity corpus browser	Browse all local skills/agents/corpora; inline search
Drag-and-drop comments	Drop files into stone comments; upload auto-appended as links
PyPI installable	pip install claude-ns-hub && claude-ns-hub — done

Troubleshooting

tmux not found

# Ubuntu / Debian / WSL
sudo apt install tmux

# macOS
brew install tmux

# Verify
tmux -V

The hub auto-creates a tmux session named claude-exec-<PROJECT> when you dispatch work. If tmux is missing, exec sessions will fail silently — install it first.

Claude Code CLI not authenticated

# Check if installed
claude --version

# If missing, install via npm
npm install -g @anthropic-ai/claude-code

# Then authenticate
claude login

The hub reads claude from your PATH. If you installed it via nvm or a custom path, set it in ~/.hub/config.yaml:

defaults:
  claude_code_path: /full/path/to/claude

Hub can't find my project

Add the project manually via the UI (North Star → "+ node" → set repo_path) or use:

hub init <PROJECT_ID> --dir /path/to/your/project

Hooks not firing

# Install hub hooks once per machine
hub install-global

# Verify hooks are registered in Claude settings
cat ~/.claude/settings.json | grep hub

Metrics endpoint

curl http://localhost:9000/api/metrics?proj_id=MOAT
# → stones_completed, stones_queued, total_tokens per day

Configuration

# Disable entity corpus auto-spawn
ENTITY_CORPUS_DISABLED=1 claude-ns-hub

# Custom entity corpus path
ENTITY_CORPUS_SERVER=~/my-corpus/server.py claude-ns-hub

Screenshots

Mobile dark theme — full UI on iOS/Android. Tap a card to see exec session, queue stones, resume Claude:

North Star swimlane — all projects across lanes (Cron / HI-TECH / Vertical / SVTool), badge counts, live exec indicator, parent-child links:

Project detail card — North Star goal, progress bars, model/session selector, live exec session row with resume ID, milestone sub-star list:

Skill / Agent badge picker — assign /expert-research or any agent to a stone directly from the milestone row:

North Star swimlane (previous) — earlier view showing project card layout:

---

pip install claude-ns-hub — because you should know what Claude is doing right now.