Claude Nine

A localhost workspace hub with an embedded Claude Code terminal. It runs as a small Node server on your machine and serves a web UI in your browser — no Electron shell, no installer, no code signing.

Inside: todos, notes, an AI-generated morning brief, cross-session search over your ~/.claude/projects history, and per-project outstanding-work ledgers, all alongside a real Claude Code terminal you can drive from the same window.

Install

npm install -g @three-rocks/claude-nine

Requires Node ≥ 20.

Run

claude-nine

This starts the server, prints a URL with an auth token, and opens it in your default browser. Flags:

| Flag | Effect | | --- | --- | | --port <n> | Preferred port (default 4909). If taken, tries the next ports up to 4919 before giving up. | | --no-open | Start the server without launching a browser tab. | | --workspace <dir> | Open a specific workspace folder on startup instead of the last one used. |

If an instance is already running, running claude-nine again just opens the existing one instead of starting a second server.

Update

npm update -g @three-rocks/claude-nine

The app also checks npm for a newer published version once a day and shows an in-app banner when one is available — it never updates itself, you still run the command above.

The bundled ledger skill

On first run, Claude Nine installs a Claude Code skill (ledger, for tracking outstanding work per project) to ~/.claude/skills/ledger. You'll see a one-time notice in the UI when this happens.

If that folder already exists and its contents don't match what Claude Nine last installed (e.g. you edited it, or it predates Claude Nine), the app treats it as user-modified and leaves it alone — it will never silently overwrite a skill directory it doesn't recognise as its own untouched install.

MCP tools

In Settings, you can toggle "Expose workspace as MCP tools" to write a .mcp.json into the open workspace, pointing Claude Code sessions at an MCP server bundled with the app (todo read/write, etc.). Toggling it off removes the file.

Install as an app (PWA)

Claude Nine serves a web app manifest, so Chrome and Edge will offer "Install app" (or you can trigger it from the browser's menu) to pin it as a standalone window with its own taskbar/dock icon, separate from your regular browser tabs.

Relaunching the installed app works as long as the claude-nine server process it was opened from is still running — it reuses the token saved in the browser's local storage. If that process has stopped (you closed the terminal, restarted your machine, etc.) and a new one has started, the saved token no longer matches; you'll see a "Claude Nine is running locally" screen instead of the app. Re-run claude-nine in your terminal and open the fresh link it prints — the installed app window will pick up the new token the next time you relaunch it from that link.

Dev setup

git clone <repo>
cd claude-nine-app
npm install
npm run dev

npm run dev runs the esbuild-bundled server and the Vite client dev server concurrently. Open http://127.0.0.1:5910/?token=<token>, using the token printed in the server's console output — the Vite dev server on :5910 proxies /api and /ws through to the real server on :4909, it doesn't serve the app itself.

Tests

npm test               # unit + integration (vitest)
npm run test:watch     # watch mode
npm run typecheck      # tsc --noEmit on both the node and web configs
npm run test:e2e       # Playwright

Build / pack

npm run build          # typecheck + server + client + mcp bundles
npm pack               # produce the installable tarball

Troubleshooting

• "claude-nine: command not found" / version errors — check node -v is 20 or newer.
• Port already in use — Claude Nine automatically tries the next port up from 4909 through 4919. If all eleven are taken, pass --port with a free one.
• "Server restarted" overlay — the terminal disconnects and shows this when the underlying claude-nine process has stopped or been replaced (e.g. you restarted it manually, or it crashed). Re-run claude-nine in your terminal and open the fresh URL it prints — the token in the old tab's link is no longer valid.
• Links inside the terminal/notes don't open — file:// links are inert because the app is served over http:// (browsers block navigating to file:// from an http:// origin, regardless of whether it's a regular tab or the installed PWA). This is a known limitation; open the path manually instead.

Architecture

See docs/superpowers/specs/2026-05-14-claude-nine-app-design.md in the parent workspace for the design doc.