Beach House — powered by Claude

A pixel-art beach house where your Claude Code sessions come to work. Every session walks in as a character and takes a desk, every subagent is an intern running errands, and you drive Claude Code from the house: prompts, approvals, questions, plans, interrupts, model and effort, compaction, rewind, replays of past sessions, night-shift jobs and more. It runs on your own computer with the Claude Code you already use — no account, no API key.

npm install -g beach-house && beach install && beach open

The website: spaceventure.lukog.in/beach-house · the package: npmjs.com/package/beach-house

The demo above is a demo house with synthetic sessions, recorded with node tools/record-demo.mjs (the MP4 is demo.mp4).

What it is

• A house that shows the work. Terminal and house sessions are characters at desks; subagents run errands and report back in speech bubbles. The whiteboard holds the live to-do list, the tiki bar every command and test run, and the sky clouds over while a session waits for you and rains while one keeps failing (or, if you like, follows your town's real weather). A booth calls the big moments like a cricket match, and the lo-fi soundtrack follows the work.
• Drive Claude Code from it. Start sessions at the Boss's desk and steer them from the browser, or from your phone over your own tailnet. Permission requests, questions and plan approvals from your terminal sessions pop up as slips in the house while you're looking at it — answer with a click, or look away and your terminal asks as usual.
• Trust & Control. Twenty checks run alongside every session: receipts that hold Claude's "the tests pass" against what actually ran after the last edit, an undo point before risky shell commands, a review tour of what changed, secret and package tripwires, a compaction guard that puts your rules back, burn forecasts for your rate limits, and more. Every check has a switch in Settings → Trust & Control, and the ones that block or ask start off.
• Stay in the loop without watching. A Board sorts every chat and terminal session into Needs you · Working · Review · Idle, filtered by repo. System notifications arrive when Claude needs you, finishes a long turn or stops on an error, and only while the house isn't in front. A chat that stops on the 5-hour or weekly limit continues on its own after the reset. Near a full context window, you're offered a hand-off to a fresh chat with a brief.
• Rich chats. Pasted images stay in the conversation; Claude's screenshots and image paths render inline; Mermaid diagrams and charts (flowcharts, swimlanes, sequence, gantt, pie, bar and line charts, mindmaps and more) are drawn in the chat. Chats get short auto-titles, and ⌘K searches every chat you've had. The chat panel resizes and reflows down to phone width.
• Memory & rules. See, edit and forget what Claude carries into each project — CLAUDE.md, AGENTS.md, rules files and Claude's own memory notes — with sizes, staleness and a backup of anything you change.
• The Conference Room. A panel of agents with different lenses (plus a devil's advocate) reads your code and debates a question item by item until they agree. Then a moderator writes the verdict, and optionally a finished document, fact-checked against the code. It runs end to end (it never stops to wait for you) within a time limit you set.
• The Archive. Every past session in ~/.claude/projects, indexed on your computer: search, replays on the TV, "why did we…?", a decision log, stand-ups and a weekly Wrapped.
• After hours. Housemates, a DJ, parties on the roof, stargazing, the odd meteor shower. You level up by what Claude can prove (receipts, reviews, green tests), never by how much it spends, and levels unlock decor.
• Space Venture, optional. A community hub with chat, rankings and a galaxy of houses. Off until you light the beacon; then it receives counts and what you type there — never your prompts, code, paths or project names.

Screenshots

| | | |---|---| | | | | The house at work | A terminal permission, answered from the house | | | | | A chat with its receipt | The session inspector (Trust & Control) | | | | | The Archive and its decision log | After hours |

Install

You need macOS or Linux, Node.js 22.13+, Python 3, and Claude Code installed and signed in (claude works in your terminal). Beach House drives your own Claude Code with your own login — there are no API keys to set up.

npm install -g beach-house
beach install      # connect Claude Code: hooks + a statusline tee (backs up ~/.claude/settings.json first); starts the house
beach open         # open the house in your browser

Every Claude Code session you start in a terminal now walks into the house. Start sessions from the house at the Boss's desk (Talk) to steer them fully from the browser or your phone. beach help lists every command; beach update installs a newer version.

If it won't start

Run beach doctor first: it checks Node, Claude Code and your sign-in, python3, the hooks, the port and the version, and prints the exact fix for anything that's off.

• No such built-in module: node:sqlite: your Node is older than 22.13. npm only warns about that, so it installed anyway. Switch to a newer Node (nvm install 22 && nvm alias default 22, or brew install node), then run npm install -g beach-house && beach install again.
• ENOVERSIONS / "blocked by cooldown": a package guard (such as SafeDep PMG or pnpm's minimumReleaseAge) holds back npm releases for a few days after they're published. Wait it out, or allow beach-house in that tool if your team's policy permits.
• The house is closed: beach start, then beach status. The server log is ~/.claude/beach/server.log (beach logs follows it).

What Beach House changes on your machine

~/.claude/settings.json — beach install (and the house's "update hooks" button) reads it, refuses to touch it if it isn't valid JSON, copies it to ~/.claude/settings.json.bak-beach-<timestamp>, and then adds:

• Hooks that run python3 "<package>/hook/forward.py" …, where <package> is where npm installed beach-house:
  • 18 events reported in the background (async): SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, SubagentStart, SubagentStop, Notification, PreCompact, Stop, StopFailure, PostCompact, InstructionsLoaded, PermissionDenied, TaskCompleted, PostModelSwitch, CwdChanged.
  • 5 synchronous ones (--sync) the house may answer for Trust & Control: PreToolUse and PostToolUse for Bash|Edit|Write|MultiEdit|NotebookEdit, Stop, PreCompact and SessionStart. They give up silently after 1.5 s and never start the house.
  • PermissionRequest, which waits for your answer in the house while you're looking at it (up to 90 s by default), then hands the prompt back to your terminal.
• A statusline tee: your existing statusline command is wrapped as "<package>/hook/statusline-tee.sh" <your command> so the house can read context %, cost and rate limits; your command still prints exactly what it printed. The original is saved in ~/.claude/beach/statusline.orig.json and put back on uninstall. If you had none, the tee alone is added (it prints nothing).

Entries that aren't Beach House's are never changed. Running beach install again replaces only Beach House's own entries, so it's safe to repeat (and needed if you reinstall the package somewhere else, such as under another Node).

~/.claude/beach/ — the house's data folder: token (the house key, readable only by you), server.log, its settings and stores, and SQLite databases — the Archive index of your transcripts and the Trust & Control ledger (ledger.db, readable only by you, pruned after 30 days).

A local server on 127.0.0.1:7777 — plain node:http, listening only on this computer. Apart from a health check and Spotify's sign-in redirect, its API only answers requests that carry the house key. The hooks start it in the background when a session starts or you send a prompt; beach stop closes it. When a terminal task has been running for a while and nobody has the house open, it opens itself in your browser (at most every 20 minutes; Settings → Scene → Open the house automatically).

Your git repositories — before a risky shell command (rm -rf, git reset --hard, …) the house saves an undo point: your working tree as a commit under a hidden ref, refs/beach/snap/<session>/<n>, written through a separate index so HEAD, your index and your stash are untouched. Nothing is pushed, and the refs are pruned after 7 days (switch it off in Settings → Trust & Control). Outside git, a bounded copy of the affected paths goes into ~/.claude/beach/.

Nothing else by default — no launch agents or system services, no shell-profile edits, no global git config, no sudo. Some extras change more, and only when you start them: beach phone configures Tailscale Serve; a surf-off creates two git worktrees and beach/surfoff-* branches; provenance notes (off by default) attach git notes under refs/notes/beach; the rule simulator writes an allow/deny rule to your Claude Code settings after showing you the diff.

Uninstall

beach uninstall              # remove the hooks, restore your statusline (backs settings.json up first)
beach stop                   # close the house
npm uninstall -g beach-house
rm -rf ~/.claude/beach       # the house's data: the Archive index, the ledger, settings

Undo points left in a repository can be removed from inside it with git for-each-ref --format='delete %(refname)' refs/beach/ | git update-ref --stdin. The settings.json.bak-beach-* backups in ~/.claude/ are yours to keep or delete.

Privacy

• No telemetry. The house sends no analytics and no usage reports.
• Your sessions stay on your computer. Transcripts are read from ~/.claude/projects (read-only); the house's records live in ~/.claude/beach/, including images pasted into chats (media/, pruned past 500 MB). The Trust & Control ledger stores commands with secrets masked.
• What leaves your computer on its own:
  • Helper calls to Claude — commentary lines, the decision log, postcard captions, "why did we…?" answers and similar short tasks (also chat auto-titles) run on Claude Haiku 4.5 through your own Claude Code login (no separate key). They see excerpts with secrets masked, run rarely and at a capped rate, and count toward your Claude plan. Set BEACH_LLM=off in the environment the house starts from (your shell profile) to turn them all off; local templates and heuristics take over.
  • A daily release check — a plain GET /api/v1/releases/latest to the Space Venture hub that sends nothing about you or your house. Switch it off in Settings → Scene → Check for updates daily.
  • Package look-ups — before Claude installs a package, its name is looked up on that ecosystem's public registry and download stats (npm, PyPI, crates.io, the Go module proxy, RubyGems) to catch made-up or look-alike names. Only the name is sent. Switch it off in Settings → Trust & Control.
• Opt-in only:
  • Space Venture stays off until you light the lighthouse beacon. It then receives a small fixed status feed — counts (sessions, tools, tests, commits…), your level and decor ids, whether Claude's API is busy (for its space weather), whole-dollar increments of your spend for its sand-dollar economy, and your house's look — plus whatever you type there yourself (chat, a status line, your handle). Never prompts, code, file paths, project or repo names, commands or tool output. The house keeps the last 100 frames it sent, exactly as sent, in its beacon log.
  • Real weather (Settings → Scene → Weather): your town's name goes to Open-Meteo once to find it, then its coordinates every 15 minutes for the forecast. Nothing about it goes to Space Venture.
  • Connections (⌘K → Connections): if you connect GitHub, GitLab, Bitbucket, an email inbox (IMAP) or an alert service (Alertmanager, Grafana, Datadog, PagerDuty, Sentry, GitHub Actions, uptime URLs), the Mailbox and the Lifeguard call that service directly on their schedule. Your tokens and app passwords are kept in ~/.claude/beach/connectors.json (readable by you only) and sent only to the service they belong to; email is read read-only (headers of unread mail; nothing is marked read).
  • Spotify (connector or your own developer app), phone access over your own tailnet (beach phone), and Lifeguard / PR-courier patrols over your own MCP servers.

FAQ

Does it work on Windows? Not natively: Beach House supports macOS and Linux, and npm refuses to install it elsewhere. WSL 2 runs Linux, but Beach House hasn't been tested there.

Do I need an API key or an account? No. It uses the Claude Code you already have, signed in with your account. Space Venture is optional and has its own sign-up inside the house.

What does it cost? Installing it costs nothing. Claude usage is billed as usual: house sessions are ordinary Claude Code sessions on your plan, and the helper calls are short Haiku completions (BEACH_LLM=off turns them off).

Will it slow Claude Code down? Most hooks report in the background; Claude Code doesn't wait for them. The synchronous ones answered in about 40–60 ms in testing and give up silently after 1.5 s.

What if the house isn't running? Claude Code carries on exactly as before: the hooks return at once and permission prompts appear in your terminal. Starting a session starts the house again in the background.

Can the house approve things on its own? No. Slips wait for you, and a terminal's request only goes to the house while you're looking at it. Scheduled jobs and the night shift run unattended, so anything that needs approval is denied, and they never commit, push or merge.

Is it made by Anthropic? No. Beach House is an independent project that runs on top of your own Claude Code. "Claude" and "Claude Code" are trademarks of Anthropic, PBC. See LICENSE.

A tour of the house

| Where | What it does | |---|---| | Boss's desk, desks | Talk to Claude: new sessions, streaming chat, images, voice input, slash commands, resume and fork terminal sessions | | Permission slips | Approve or deny tool use, answer Claude's questions, approve plans — for house sessions and (while you're looking) terminal sessions | | Coffee machine, bell, trash, door | Model, effort and permission mode · interrupt · compact · a new day · rewind files | | Whiteboard, tiki bar, desk | Live to-dos and plans · every Bash command and test run · git status, diffs, sticky notes to CLAUDE.md | | Corkboard, tool shelf, tip jar | Claude's memory files · MCP servers, skills, slash commands · spend and rate limits | | Archive, TV, bonfire | Session viewer, decision log, "why did we…?" search · replays with a director's cut · the weekly Wrapped | | Booth, jukebox | Live IPL-style commentary (English, Tanglish or a duo) · an adaptive lo-fi soundtrack driven by Claude's work | | Alarm clock, night shift | Scheduled jobs · an overnight task queue with a morning newspaper from Bugsy | | Lifeguard, mailbox, surf rack | Alert patrol over your alerting MCP servers → RCA · pull requests awaiting your review, from your code-host MCP servers → review · surf-off: two approaches race in git worktrees | | Trophies, postcards, arcade | Achievements that unlock house decor · daily postcards · games while you wait | | Lighthouse, telescope | Space Venture: light the beacon to share a small fixed status feed (every frame is in the beacon log) · chat, rankings, the galaxy · the shop: sand dollars minted from whole dollars in your tip jar, decor for the house, tips, fireworks, visitors landing on your beach, trades · pick Dark Space, your time zone or a city | | Bugsy | Barks at failures, tilts at approvals, recaps what happened while you were away, and reminds you to take walks | | Neon sign | The Customize studio (also ⌘K, Settings → Scene): wall, trim, roof and wood colours, the awning, a flag, your own sign text and neon, Bugsy as a corgi, beagle, lab or cat, the crew's outfit, and the decor you own from Space Venture placed on the deck, beach, roof, sea and walls. Visitors in Space Venture see the same house |

Phone

beach phone sets up Tailscale Serve and prints a private link for your phone (only reachable on your tailnet). The link contains your house key. Settings → Phone shows the same link as a QR code.

How it works

• hook/forward.py — Claude Code hooks (async) post lifecycle and tool events to the local server; PermissionRequest waits for an answer from the house only while you're looking at it. A few hooks run synchronously (forward.py --sync: PreToolUse/PostToolUse for Bash and file edits, Stop, PreCompact, SessionStart) so Trust & Control can answer — block a risky command, hand Claude a note, put your rules back after compaction. They give up silently after 1.5 s, and when the house is closed Claude Code carries on as if they weren't there. Upgrading from an older house? The house shows a one-time card to update the hooks (or run beach install again).
• hook/statusline-tee.sh — wraps your statusline to share context %, cost and rate limits.
• server/ — plain node:http server on 127.0.0.1:7777 with token auth, SSE, the Claude Agent SDK for house-driven sessions, and a SQLite archive of ~/.claude/projects transcripts. Helper LLM calls (commentary, decisions, summaries) use Claude Haiku 4.5 through your Claude Code login.
• public/ — vanilla JS + canvas pixel art, no build step. See CONTRACTS.md for the architecture. The house exterior art lives in public/js/scene/postcard/ — a self-contained renderer (renderHouse) that Space Venture reuses for its visit view; the look is the house.look setting.

Trust & Control and the ledger. The house keeps a ledger of what each session actually did — commands with their exit codes and timings, file edits, the rules files that loaded, compactions, token counts — in ~/.claude/beach/ledger.db on your computer. It is used for receipts, undo, the session inspector (click a character or a session tab, then Inspect) and friends. None of it goes to Space Venture or anywhere else. Every check has a switch in Settings → Trust & Control; the ones that block or ask start off.

Recording the demo. node tools/record-demo.mjs starts a throwaway house on port 7951 (fake HOME, sample transcripts, helper AI calls off), plays scripted sessions into it, films it in headless Chromium and writes the GIF, the MP4 and the stills to docs/media/. --help lists the options.

More music: internet radio, your files, YouTube

The Jukebox has five sources: Beach radio (generated, follows your work), Spotify, Internet radio (live stations from the free, open Radio Browser directory — no account), My music (audio files in a folder under your home, ~/Music by default; they never leave your computer) and YouTube (paste a video or playlist link; to search, add your own free YouTube Data API key — it stays in the house's data folder). Every source plays a list: Play all or Shuffle all, pick a song and the rest follow, and set Repeat to off, all or one.

Spotify (optional)

Open the Jukebox and switch the source from Beach radio to Spotify. There are two ways to connect.

Connect through Claude (default). Spotify has an official connector for Claude.

1. In the jukebox press Connect Spotify — it opens https://claude.com/connectors/spotify.
2. Click Add to Claude there and sign in to Spotify (connectors can only be added on claude.ai).
3. Come back: the house checks claude mcp get "claude.ai Spotify" every few seconds and lights up when it's connected.

Then ask the DJ ("bossa nova for a slow afternoon") or tap a mood — Focus, Chill, Night shift, Hype. The connector can't start playback, so the DJ returns picks that open in Spotify — or, if Play in the house is set up, the top pick plays right there (the next one if Spotify refuses it). "What's playing?" and vibe playlists need a one-time sign-in for Claude Code: run claude, type /mcp, pick claude.ai Spotify (plain picks work without it). Each DJ request is a short Claude Haiku chat on your Claude plan; the DJ only sees what you typed or the mood name. Auto DJ suggestions (off by default) leave mood picks when the house mood changes, at most once every 20 minutes — never starting music.

Play in the house (recommended for real play/pause/skip — Premium + your own developer app). The house tab becomes a Spotify speaker called "Beach House".

1. Have Spotify Premium. Create a free app at https://developer.spotify.com/dashboard — any name without "Spotify" in it — and tick Web API and Web Playback SDK.
2. Add the redirect URI the jukebox shows, exactly: http://127.0.0.1:7777/api/spotify/callback (your port if you changed it; localhost isn't accepted by Spotify).
3. Paste the app's Client ID into the jukebox and press Connect. No client secret is used (PKCE).
4. Development-mode apps work for up to five Spotify accounts — add other people under User Management. Use a desktop browser on the computer running the house (phones can't play Spotify in a tab; they can still control your other devices). Brave ships with Widevine off: enable it in brave://settings/extensions and relaunch.

No overlap. Spotify's rules forbid mixing its music with other audio, so while Spotify plays in the house the generative score is stopped, effects and alert chimes are silent (you still see them), and the commentary becomes captions. "Commentator cuts in" (Never / Big moments / Every line) pauses the song for a line, speaks it, then carries on — it never talks over the music. The jukebox LEDs show house activity, not the music.

Privacy. Connect through Claude: the Spotify sign-in lives with the connector in your Claude account; the DJ's short Claude chats aren't saved as sessions or transcripts, and what they find is only shown in the jukebox (kept in memory, never logged). Play in the house: the sign-in stays on this computer (~/.claude/beach/spotify.json, readable only by you) and your music never leaves the browser except in calls to Spotify. Either way, what you listen to never reaches the house's logs or event feed, the commentator, the archive, your Claude Code sessions, trophies or Space Venture. Disconnect any time from the jukebox (and remove the app under Apps on your Spotify account page).