Content
# Project Hub
**AI is working, and the desktop is showing progress.**
A local project cockpit that resides on the macOS desktop: transform each folder under the project root directory into a card with a progress ring - your AI (Claude Code / Cursor / Codex / any local model) edits a `.project.json` file, and **within 1 second**, the progress ring on the desktop starts spinning.
## Why Do We Need It?
When you're working on a dozen projects simultaneously, with one or more AIs working in parallel, the real problem isn't "getting things done," but rather **"where are we now?" - progress is scattered across a dozen terminals, chat logs, and HANDOFF documents**.
project-hub's answer: **don't disrupt any workflow, just passive observation**. AI works in its own tools, casually writes a JSON file, and the desktop automatically displays the overall progress, categorized progress, and which milestone each project is stuck in - AI just made a move.
> It's not another task scheduler (that space is already crowded), but rather a **project-level ambient display** - like a dashboard on the wall, not another website you need to log in to.
## Key Features
| Capability | Implementation |
|---|---|
| **1-second real-time updates** | macOS FSEvents file listening (not polling): `.project.json` is written, and the desktop updates within 1 second; windows in the background work too |
| **Zero-configuration access** | Files are the interface - any AI/script/human that can write files, writes a JSON file to access, no SDK, no registration, no token |
| **MCP Native** | Comes with a zero-dependency MCP server (single file, 4 tools), Claude Code / Cline, and other MCP clients can connect with one line of configuration |
| **Incremental scanning** | Cached with mtime triplets, 100 projects only re-read the ones that actually changed |
| **Local-first** | Data is just files on your disk; HTTP port only bound to 127.0.0.1; zero cloud, zero uploads, zero accounts |
| **Always-on desktop** | `⌘⇧P` to sink into desktop icons, doesn't occupy Dock, doesn't interfere with Cmd-Tab |
## Installation (macOS · Apple Silicon)
1. Download [Releases](../../releases) `project-hub_x.x.x_aarch64.dmg`, drag it into Applications.
2. If prompted "can't verify developer" on first open: System Settings → Privacy & Security → "Still allow" (or `xattr -cr /Applications/project-hub.app`).
3. Follow the first-run guide to select your project root directory - done.
## Get Started in 3 Steps
```jsonc
// Place a .project.json file in any project folder
{
"name": "My Project",
"category": "Engine", // Research | Engine | Culture | Others
"emoji": "⚙️",
"tagline": "One-sentence intro",
"status": "active", // active | done | failed
"goal": "One-sentence goal",
"branches": [
{ "name": "Mainline", "milestones": [
{ "title": "First milestone", "done": true },
{ "title": "Second milestone", "done": false }
]}
]
}
```
Progress = completed milestones / total. **Editing this file takes effect immediately**. Folders without `.project.json` show as "To Be Estimated," click to let the built-in AI scan the folder contents and draft a proposal.
## Connect Your AI (Choose One)
| Method | Applicable | Access Cost |
|---|---|---|
| **File Protocol** (recommended) | Any AI that can write files | Paste the "↔️ → Connect your AI" agreement into CLAUDE.md / .cursorrules / system prompts, **one-time paste** |
| **HTTP API** | Any program that can make requests | `127.0.0.1:3120`: `GET /api/projects` · `POST /api/project/{create,update,delete}` · `GET/POST /api/config` |
| **MCP** | Claude Code / Cline, etc. | `scanner/mcp-server.mjs` (zero-dependency single file), client configuration in one line, get 4 CRUD tools |
AI changes are rolled into the "AI Activity" stream in real-time and trigger native system notifications - **when you're not looking, it's still watching for you**.
## Architecture (understood in 1 minute)
```
Your project folders project-hub.app (Tauri 2)
┌──────────────┐ FSEvents ┌─────────────────────────┐
│ A/.project.json│ ──────────→ │ Rust: watcher + incremental scan │
│ B/.project.json│ │ ├─ HTTP :3120 (localhost) │ ←── curl / any program
│ C/HANDOFF.md │ │ └─ emit("projects-changed")│ ←── MCP server (stdio)
└──────────────┘ │ React: cockpit UI (desktop) │
↑ write files └─────────────────────────┘
Any AI / anyone
```
Tech stack: Tauri 2 (Rust) + React 18 + Vite. No database, no backend service, no network dependency.
## Development
```bash
npm i
npm run dev # browser development
npx tauri dev # desktop window development
npx tauri build # package .app + .dmg
```
## Roadmap
- [ ] Activity stream with actual operation logs (who, what tool, what changes)
- [ ] Native directory selector / signature notarization / auto-update
- [ ] Windows / Linux (desktop is macOS exclusive, others are portable)
- [ ] Weekly report view: summary of project progress for the week
## Acknowledgements
This project was co-built by [Claude](https://claude.com) (Opus 4.8 draft, Fable 5 completed real-time mechanism and productization) and Wang Duoyu - it's itself a product of the "AI working, desktop showing progress" workflow: `.project.json` in this repo records its own milestones.
MIT License · Data is always on your own disk.
