HappyVibe

Good vibes, real code.

Everything set up. Nothing happens behind your back.

A desktop app for coding with AI, where everything is already set up and you can see everything it does.

Terminals, a browser, documents, git, schedules, sub-agents, MCP and skills are wired and ready — no
plugins to hunt down, no config to write, no restart. Bring any model, including a local one. And
nothing loads itself until you say yes to that specific thing.

Status: pre-1.0 and moving fast. macOS and Windows ship today. Linux builds, packages and
passes its suite on every commit, but nobody has launched it on real hardware yet — see
Honest limitations.

What it does

Everything is already here. A chat that streams, with tool cards and real diffs. A file tree and
editor. Terminals you drive and terminals the agent drives. An embedded browser the agent can read
and click. PDFs and Office documents converted on-device. A git panel that speaks human on top and
real git underneath. Scheduled runs. Sub-agents. Memory.

Any model, including your own. 29 providers covering over a thousand models, six one-click
sign-ins, and Ollama / LM Studio / llama.cpp detected automatically. Keys live in your OS keychain.
Nothing leaves your machine that you did not send.

Nothing happens behind your back. Every command is shown before it runs, in plain language.
Nothing auto-loads — no skill, extension, prompt template or theme enters a session until you
approve that specific resource. You can read the system prompt on a settings page. Every model call
the app makes on your behalf is itemised.

And the description you approve is written by the app, never by the model. Model-authored
narration goes in the activity feed; the approval dialog shows an app-derived description of what
is actually about to happen. That split is the one thing here no other tool ships as a stated rule.

Install

Download the latest release — the app
updates itself after that.

• macOS (Apple silicon): open the .dmg and drag HappyVibe to Applications. The build is
  signed and notarized, so it opens like any other app.
• Windows (x64): run the Setup.exe. It is a per-user install (no admin prompt) and is not
  code-signed yet, so SmartScreen warns on first run — choose More info → Run anyway.
• Linux (x64): the .deb installs cleanly on Ubuntu and Debian; download each new version from
  the same page. The .AppImage runs anywhere and updates itself, but needs libfuse2, which
  Ubuntu 22.04+ does not ship (sudo apt install libfuse2) — without it a double-click does
  nothing.

This is an early build, published for feedback. The in-app feedback button goes straight to us.

Run from source

npm install
cd pi-runtime && npm ci && cd ..   # BOTH installs are required
npm run dev

On Linux the first install also compiles node-pty, which publishes prebuilt binaries for
macOS and Windows only — so you need build-essential and python3 (sudo apt install -y build-essential python3). This is a prerequisite for building the app, never for running it: the
compiled binary ships inside the package.

pi-runtime/ is a separate vendored tree; a fresh clone without its install will fail in
confusing ways. No system Node is needed at runtime — the app routes child processes through its
own bundled Electron helper.

npm test      # the non-live suite — 327 files, ~3,900 tests, ~40 s. Never makes a model call.
npm run gate  # typecheck + build + the non-live suite, one command
npm run build:mac / build:win

Set a key from the app's own Models page, or drop one in .env for development.

How it is built

An Electron app driving a pinned, vendored Pi coding agent as a subprocess
over its JSON-lines RPC protocol. Pi is never imported as a library — process isolation is
load-bearing for crash isolation and session hibernation, and the RPC protocol is the only coupling
surface.

Electron renderer (React + TS + Vite)     src/renderer/
   ↕ typed IPC (contextBridge, window.hv)  src/preload/
Electron main                              src/main/
   pi/{spawn,codec,PiClient}.ts            electron-free, so tests can import them
   ↕ stdio, Pi RPC
Pi subprocess (vendored, pinned)           pi-runtime/
   extensions/happyvibe-bridge.ts          the permission gate + 30 registered tools

The runtime pins move deliberately, together with their contract tests. Their versions live in
pi-runtime/package.json, and every release lists them:

• @earendil-works/pi-coding-agent: the agent engine, MCP included (its sign-in page patched at install)
• @tintinweb/pi-subagents: sub-agents (patched at install)
• @firecrawl/anydoc: the document converter
• @earendil-works/pi-tui and typebox: moved with Pi, to exactly what it declares

The bridge owns all permission UI. Pi's own permission package is TUI-only — every prompt path
gates on ctx.hasUI, which is false in RPC mode — so the gate, the audit log and every approval
dialog are HappyVibe's. Evidence is in docs/validation/, which is also where
wire shapes get recorded before anything depends on them.

Resources are deny-by-default. The Pi subprocess is spawned with --no-skills --no-extensions --no-prompt-templates --no-themes; approved resources are then passed back in explicitly. bash is
the one filesystem writer that is not path-confined, which is exactly why an unapproved extension
must never be able to load.

Honest limitations

• Nothing is signed yet. One extra click on first launch, on both platforms.
• Linux has never been launched by a human. CI builds it, packages it as an AppImage and a
  .deb, and runs the full suite on it — but "the suite is green" is not "the window opens", and
  nobody has yet opened a terminal tab or signed into an MCP server there. It is also x64 only,
  for a different reason than Windows below: linux-arm64 binaries do exist for both native
  dependencies, and the target is excluded simply because nothing tests it.
• The Linux file tree does not refresh itself. Recursive filesystem watching does not exist on
  Linux, so a file created outside the app shows up on the next manual refresh. macOS and Windows
  update live.
• The Linux AppImage needs libfuse2, which Ubuntu 22.04 and later do not install by default —
  without it a double-click does nothing at all, with no error. The .deb has no such problem, and
  that is why both are built.
• The Windows build is x64 only. sherpa-onnx (voice) and @firecrawl/anydoc (documents)
  publish no win-arm64 binary, so arm64 machines run the x64 installer under emulation.
• The cost meter is an estimate, computed from a price table pinned at the vendored Pi version.
  It says unknown rather than $0.00 when it cannot price a call — but a provider that prices
  only part of a call is reported as a floor, marked +.
• It is not a sandbox and does not claim to be. The gate is an in-process extension. It asks
  before it acts; it is not a security boundary.

Contributing

Issues and pull requests are welcome — CONTRIBUTING.md has the setup and the one
rule (sign your commits with git commit -s). Security reports go through
SECURITY.md, never a public issue.

Licence

Apache-2.0 — see LICENSE. Third-party attributions are in NOTICE.

Permissive on purpose: use it, fork it, ship it in something commercial. The name and the logo are
not covered (Apache-2.0 §6), so a fork needs its own.

Everything HappyVibe does runs on your machine with your own API keys. The one exception is the web
search and scraping service, which is ours by default and which you can repoint at your own
Firecrawl-compatible endpoint under Settings → Built-in tools → Web service.

Docs

• docs/prd.md — the product spec, decisions folded in place
• docs/validation/ — measurements and wire shapes, including the negative results
• CHANGELOG.md — what changed, in user terms
• CLAUDE.md — the working notes an agent needs to change this repo safely