Project overview

codehelm

A local-only web UI that puts every Claude Code session and a real shell for each project into one Chromium window — reading the ~/.claude/projects JSONL you already have, spawning live terminals per tab, and never touching the cloud.

The stack, explained

nextframework15

A React framework for building full-stack web apps, with file-based routing, server rendering, and bundling built in. The App Router organises pages, layouts, and API route handlers in one tree.

Here: powers the App Router UI and rides on a custom http.Server for the HTTP path.

reactui library19

A JavaScript library for building user interfaces out of composable components whose output updates as their data changes. It is the rendering layer most of the modern web is built on.

Here: renders the whole interface — sidebar, conversation viewer, and terminal tabs.

node-ptypseudoterminal0.12

A Node.js library that forks a real pseudoterminal (PTY) process, so you can spawn and drive shells exactly as if they were running in a terminal. It is the foundation for terminal emulators built on Node.

Here: forks the real shells behind every terminal tab.

why this choice →
xterm.jsterminal emulator5.5

A front-end terminal emulator component that lets a web app embed a fully-featured terminal in the browser. It renders terminal output and handles keyboard input for shells and command-line programs.

Here: draws those shells in the browser, addons for fit, WebGL, and links.

wswebsocket8.18

A simple, fast WebSocket client and server implementation for Node.js. It keeps an open, two-way connection so a server and browser can exchange messages in real time.

Here: carries PTY bytes and file-watcher events over one authenticated socket.

why this choice →
chokidarfile watcher4.0

A cross-platform Node.js library for watching files and folders and reacting to add, change, and delete events. Build tools and dev servers use it to trigger work automatically when files change.

Here: watches ~/.claude/projects/ for live session changes.

why this choice →
cronerscheduler10.0

A JavaScript and TypeScript library for scheduling tasks with cron expressions, running a function at set times or intervals. It can also compute when the next run of an expression is due.

Here: fires scheduled prompts into persistent Claude tabs.

why this choice →
zustandstate5.0

A small, fast state-management library for React with a simple hook-based API for sharing data across components, without the boilerplate of heavier stores.

Here: holds local UI state — open tabs, panes, and layout.

react-queryserver state5.62

A library for managing server state — the fetching, caching, synchronising, and updating of data from APIs. It removes much of the manual work of loading remote data and keeping it fresh.

Here: fetches and caches projects and sessions from the REST API.

react-virtuosovirtualization4.12

A React component for rendering very long lists and tables efficiently by drawing only the items currently on screen. It handles items of varying sizes so large datasets scroll smoothly.

Here: virtualises the long conversation and session lists.

why this choice →
zodvalidation3.23

A TypeScript-first schema validation library that describes the expected shape of data and checks that real values match it. From one schema it also infers the matching static types.

Here: validates every request body and JSONL event shape.

tailwindcssstyling4.0

A utility-first CSS framework that styles elements through small, composable classes applied directly in markup, instead of writing separate stylesheets. It keeps styling close to the components.

Here: styles the interface alongside shadcn / Radix primitives.

shikihighlighting1.24

A syntax highlighter that colours source code using the same TextMate grammars and themes as code editors, producing accurate, editor-quality highlighting for code blocks on the web.

Here: highlights code blocks inside rendered sessions, loaded lazily per language.

full stack
Production
react-dom 19.0.0@codemirror/commands 6.10.3@codemirror/lang-markdown 6.3.0@codemirror/state 6.5.0@codemirror/theme-one-dark 6.1.2@codemirror/view 6.35.0@radix-ui/react-dialog 1.1.15@radix-ui/react-popover 1.1.15@radix-ui/react-scroll-area 1.2.10@radix-ui/react-slot 1.2.4@radix-ui/react-tooltip 1.2.8@radix-ui/react-visually-hidden 1.2.4@xterm/addon-canvas 0.7.0@xterm/addon-fit 0.10.0@xterm/addon-web-links 0.11.0@xterm/addon-webgl 0.19.0class-variance-authority 0.7.1clsx 2.1.1cmdk 1.1.1diff 7.0.0lucide-react 1.8.0pino 9.5.0react-markdown 9.0.1react-resizable-panels 4.10.0rehype-sanitize 6.0.0sonner 2.0.7tailwind-merge 3.5.0tw-animate-css 1.4.0
Dev
typescript 5.7.0tsx 4.19.0vitest 2.1.8@vitest/ui 2.1.8@playwright/test 1.49.0@testing-library/react 16.3.2@testing-library/dom 10.4.1@testing-library/user-event 14.6.1jsdom 29.0.2supertest 7.0.0@types/supertest 6.0.2eslint 9.16.0eslint-config-next 15.0.0eslint-plugin-react-hooks 7.0.1@eslint/eslintrc 3.2.0prettier 3.4.0husky 9.1.7lint-staged 15.2.10pino-pretty 13.0.0@tailwindcss/postcss 4.0.0@types/node 22.10.0@types/react 19.0.0@types/react-dom 19.0.0@types/ws 8.5.13@types/diff 7.0.0

Why this stack

node-pty behind client-ACK backpressure

A real shell can out-run the browser, so the PTY is paused at 1 MB unacked and capped at 16 tabs — bounded memory no matter what runs.

full decision in the course → what is node-pty ↑

One http.Server for HTTP and raw WebSockets

A single listener means one bind, one Origin check, and one cookie to secure — instead of a second server doubling the attack surface.

full decision in the course → what is ws ↑

croner fires prompts only when Claude is idle

A ready-check, a per-tab mutex, and bracketed paste land a scheduled prompt at the input prompt — never in the middle of a streaming response.

full decision in the course → what is croner ↑

chokidar watch, not interval polling

An OS-level watch costs nothing until a session file actually changes, then pushes the update over WebSocket — the opposite spend profile from a poll.

full decision in the course → what is chokidar ↑

react-virtuoso over render-everything

Virtualising mounts only the rows on screen, so a 2000-message session scrolls above 30 fps instead of freezing the tab on open.

full decision in the course → what is react-virtuoso ↑

What it gives you

Glossary

PTY (pseudoterminal)
A pair of virtual devices that emulates a real terminal, letting one program drive another as if a user were typing and reading at a physical terminal.
JSONL
JSON Lines — a text format where each line is one complete, independent JSON value, well suited to streaming and large logs read one record at a time.
backpressure
Flow control where a slower consumer tells a faster producer to slow down, preventing unbounded buffering, memory blow-ups, or dropped data.
bracketed paste
A terminal mode that wraps pasted text in marker sequences so a program can tell pasted input apart from typed keystrokes and handle it differently.

The numbers

Data

Lines of code, work time across sessions, the language split, and the full file breakdown — the dry numbers behind codehelm.

Why it's built this way

Course

A cinematic "why" course — the architectural decisions, the traps they avoided, and the roads not taken.

Audited & remediated

Security

security audit not run yet