Codehelm

codehelm


A local-only command center for your Claude Code CLI sessions. One Chromium window. Every project. Every session. A real shell in every tab. Zero cloud. Zero extra API cost. And a security model that treats `127.0.0.1` like the attack surface it actually is.

Built as a defense-in-depth exercise on top of Next.js 15. Eight phases plus a quarter of feature work on top. 564 unit + integration tests, 7 end-to-end specs, zero `pnpm audit` findings, one tightly-scoped PTY multiplexer.

---

Quickstart

Requirements: **Node 20.11+**, **pnpm 9+**, and **Chromium** or **Google Chrome**.

Linux (primary target — Ubuntu 22.04+ tested)

git clone https://github.com/bartek-filipiuk/codehelm.git
cd codehelm
pnpm install
pnpm build      # one-time — without this, codehelm falls back to dev mode (slower)
./bin/codehelm

A dedicated Chromium window opens on a random ephemeral port with a one-shot auth token. Close the window or hit `Ctrl+C` in the terminal to tear everything down — PTYs, watcher, and the Chromium profile are cleaned on exit.

Re-run `pnpm build` (or `./bin/codehelm --build`) whenever you pull new source changes. Use `./bin/codehelm --dev` if you want HMR and don't mind the slower cold start.

macOS (verified on Darwin 25.4 arm64)

The codebase has macOS-aware helpers (`lib/server/platform.ts`) for:

• Chrome discovery at /Applications/Google Chrome.app/Contents/MacOS/Google Chrome and /Applications/Chromium.app/...
• zsh as the default shell (vs Linux's bash)
• $TMPDIR fallback when $XDG_RUNTIME_DIR is unset

git clone https://github.com/bartek-filipiuk/codehelm.git
cd codehelm
pnpm install
./bin/codehelm

✅ **Verified end-to-end on Darwin 25.4.0 (arm64), Node 22.14, pnpm 10.33, Chrome 147** (PR #7). `@homebridge/node-pty-prebuilt-multiarch@0.12.0` fetches the `darwin-arm64 node-v127` prebuild — no `node-gyp` fallback. `pnpm install && pnpm build && pnp