Metadata-Version: 2.4
Name: claude-ns-hub
Version: 0.2.25
Summary: Personal AI project management hub — North Star milestone tracking, live Claude sessions, CTX context alignment.
Author-email: jaytoone <be2jay67@gmail.com>
License: MIT License
        
        Copyright (c) 2026 jaytoone (be2jay67@gmail.com)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
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
License-File: LICENSE
License-File: NOTICE
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
Dynamic: license-file

# claude-ns-hub

[![PyPI Downloads](https://img.shields.io/pypi/dm/claude-ns-hub?label=downloads%2Fmonth&color=orange)](https://pypi.org/project/claude-ns-hub/)
[![PyPI Version](https://img.shields.io/pypi/v/claude-ns-hub?color=blue)](https://pypi.org/project/claude-ns-hub/)
[![GitHub Stars](https://img.shields.io/github/stars/jaytoone/claude-ns-hub?style=flat&color=yellow)](https://github.com/jaytoone/claude-ns-hub)
[![Python](https://img.shields.io/pypi/pyversions/claude-ns-hub)](https://pypi.org/project/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/nM5naaI.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

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

![Mobile dark — detail card](https://i.imgur.com/tjM3kwD.png)

![Mobile dark — swimlane overview](https://i.imgur.com/riH661r.png)

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

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

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

![Project detail card](https://i.imgur.com/KjCAx1B.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)

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

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

---

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