Metadata-Version: 2.4
Name: claude-ns-hub
Version: 0.2.14
Summary: Personal AI project management hub — North Star milestone tracking, live Claude sessions, CTX context alignment.
License: MIT
Project-URL: Homepage, https://github.com/jaytoone/claude-ns-hub
Project-URL: Issues, https://github.com/jaytoone/claude-ns-hub/issues
Keywords: ai,project-management,claude,northstar,milestones,productivity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Scheduling
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: ptyprocess>=0.7; platform_system != "Windows"
Requires-Dist: psutil>=5.9
Requires-Dist: anthropic>=0.28
Requires-Dist: ctx-retriever>=0.3.30
Requires-Dist: python-multipart>=0.0.9

# 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.

![Hub Dashboard — North Star swimlane with live exec sessions](https://i.imgur.com/798spzC.png)

## 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](https://claude.ai/code) installed and authenticated (`claude --version`)
- `tmux` installed (`brew install tmux` / `apt install tmux`)
- Tailscale (optional, for remote access)

## Install

```bash
pip install claude-ns-hub
```

## Quick start

```bash
# 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:

```bash
# 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 |

## Metrics endpoint

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

## Configuration

```bash
# 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

**North Star swimlane** — all projects, badge counts, live exec indicator at a glance:

![North Star swimlane](https://i.imgur.com/TG233OE.png)

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

![Skill badge picker](https://i.imgur.com/v8VRaAz.png)

---

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