Very Happy is an open-source hub for your coding agents and connected machines.
Bring sessions from your workstation, laptop, and servers into one Web/PWA
workspace. Start work on the machine and agent you choose, then follow its
conversation, terminal, files, and progress from a computer, phone, or tablet.
Your machines do the work; you stay connected wherever you are.
Use structured conversations with supported agent integrations, or open a real
terminal for your local tools. Each integration exposes its own capabilities;
ordinary terminal access does not imply identical structured support for every
agent. Connect each machine once, keep its daemon online, and use the same
workspace for a single conversation or a coordinated team.
pi conversations (very-happy pi, or pi in the Web's new-session dialog) run pi through the pi-acp adapter, so the machine needs both: npm install -g @earendil-works/pi-coding-agent [email protected]. The daemon picks them up within five minutes; very-happy pi and the dialog both show the exact command when either is missing. With CLI 0.2.181+ you can instead click Install pi on this machine in the dialog (or Install / Update on the machine page for Claude Code, Codex, Gemini CLI and pi): the daemon installs that fixed package list into the same user-level npm directory as Very Happy, never with sudo, and only when you click.
In a pi conversation, Steer sends a queued message into the turn that is running, questions a pi extension asks (select) appear as answerable question cards, and pi sub-agent runs (the subagent tool) get the same sub-agent cards as Claude. When the agent crashes or the wrapper restarts, a pi session reopens its conversation, and an archived or offline pi session can be restored from the Web like a Claude or Codex one (sessions started with a CLI that records the pi session id).
Run very-happy install-pi-tools once, then launch pi directly inside a Very Happy terminal to load terminal naming, clipboard and file preview tools. very-happy pi --terminal remains available for temporary loading. Each conversation and terminal has a Copy and preview history disclosure for reopening files and copying earlier content. Tool setup and retention limits.
What's new — October 23, 2026 (where am I)
- Projects, teams and members in one tree: the Projects view of the sidebar nests project › team › lead and members, with a badge for what needs you at every level. Session headers, team pages and project pages show breadcrumbs, and a team can move to another project from its menu.
- Just me & the lead: a lead's conversation opens on your messages and the lead's answers; member and system traffic folds into one line (every paragraph the lead writes stays, also mid-turn and while it is still working; the newest member messages show a preview), and Answered ↗ jumps to the reply.
- Tool cards show their results: command output, file contents, search results and MCP replies; failures in red, output over 32 KB cut and marked (CLI 0.2.183).
- Quieter teams: an idle member no longer interrupts the lead; idle members are summed up on the lead's next team message, with a reminder only after 30 minutes idle without a submit.
- Also: Tags and Recent list conversations with a team or project chip; linking a team from another project asks first; a pushed preview waits behind a notice instead of pulling you out of a dialog;
auto report clips long fields instead of failing; on a Mac, automatic CLI updates stay under launchd (CLI 0.2.183).
See the full update → · All releases
Projects: shared context for parallel sessions
A project groups the sessions working on one thing — across machines,
repos and agents — and gives them the same footing: instructions you write
once, a log of decisions, findings and handoffs that agents append to, and a
view of who is doing what. The sidebar groups sessions by project by default
(sessions outside any project are grouped by folder, one click to turn a
folder into a project). Claude Code, Codex, Gemini and pi sessions start with
the project's instructions in front of their first message and get a one-line
note on their next turn when something changes — idle sessions are never woken
up; harnesses that cannot be injected are marked “not injected”. Start a
session from the project page, its group's ＋, very-happy spawn --project <id>,
or let spawned and forked sessions inherit their parent's project. A new
team gets a project with its name by default, so its lead and members share the
project's instructions and log; link or change a team's project from the project
page or team settings. Project instructions, log and messages are stored on the
server.
Teams: from one goal to parallel work
Very Happy Teams brings Claude Code, Codex, and pi together around a goal.
A lead breaks it down, teammates work in parallel, and results come back for
review. Teams builds on the same conversations and machine controls you already
use, with a shared view of assignments and results.
“Review this project, find worthwhile improvements, form a team to work on them in parallel, and bring back results I can review.”
- Set the goal. Open Teams → New team and describe what you want done. Recent computer and Git project choices are shown below the message; expand them to change the computer, project, or agent.
- Let the lead organize. Very Happy starts the lead with official collaboration instructions. By default the lead delegates instead of coding itself, runs independent tasks in parallel, keeps overlapping work apart, and records decisions in the team's project so they survive context compaction. Teammates can further divide their own assignments.
- Follow parallel work. Open member conversations from the team overview and inspect progress, submitted results, and code changes.
- Review the result. Accept or return work for changes. Cleanup preserves unmerged code; a stopped process does not count as completed work.
New teams default to No approvals for the lead and newly delegated members. Change the mode in team settings when needed; existing teams and running sessions retain their permissions.
Teams requires an enabled account and a compatible online daemon. No manual
skill installation is needed when creating a team in the app. An
existing managed conversation can also become a team from its More menu.
Each team currently runs on one computer within one account, with configurable
agent, model, and concurrent work defaults. Ordinary chats and terminals keep
working as before. Automatic cross-machine routing is not available.
Start using Teams · Explore the architecture · Connect your first machine
Automations: agents on a schedule or on an event
Automations pair a trigger with an action on one of your computers: a cron
schedule with a time zone, a fixed interval, a single moment, or trigger only
(fired by an event); the action spawns an agent session in a directory, sends a
prompt into an existing session, or runs a script. Create them from the web
(Automations in the sidebar), the CLI (very-happy auto create) or from a
managed session (automation_* MCP tools). Every run is recorded, and the task
board's Needs my decision band collects the ones that failed, expired or
are waiting for you — open the session, acknowledge, run again or cancel.
very-happy auto create --name daily-inventory --cron '0 9 * * 1-5' --tz Asia/Singapore \
--spawn-dir ~/work --prompt-file prompts/inventory.md
very-happy auto fire on-mention --payload-json '{"conversationId":"c9","text":"hi"}' --dedupe-key msg-123
Automations are gated per server (VH_AUTOMATIONS_ENABLED=true) and run on the
one machine you name; there is no automatic cross-machine routing.
Automations guide · CLI and MCP contract
[!TIP]
Use the Web/PWA as your daily workspace. Install the CLI once to pair a
machine and start its background daemon. Return to the CLI for diagnostics,
automation, recovery, or an intentional local launch—not because you need to
live in a second interface. The daemon remains required: Web-first is a UX
choice, not a browser-only architecture.
[!NOTE]
Choose the deployment that fits your work. Very Happy Cloud gives you the
fastest multi-device setup; self-hosting gives you control of the operator,
access policy, storage, and backups. See the privacy and security
model for sensitive environments.
Your everyday workspace
The terminal is the compatibility layer. It forwards a real TTY and does not
care which brand—or category—of process is on the other side. A tool working in
a terminal does not automatically expose Claude-style structured events.
Durable terminals require
tmux; the optional Claude mirror requires tmux 3.2 or newer. Without tmux,
Web terminals use a non-persistent direct-shell fallback.
The browser terminal advertises TERM=xterm-256color and renders through
xterm.js. Common text TUIs are the compatibility target; sixel/Kitty graphics
and other terminal-specific extensions are not guaranteed.
Clipboard → target machine, without the detour
Paste a screenshot or drag a file straight into a Very Happy browser terminal.
The daemon receives it on the selected machine under
~/.happy/uploads/terminal/, then Very Happy pastes a path quoted for the
daemon's default shell at the terminal cursor. The chosen Cloud or self-hosted
server is the trusted relay for this bounded transfer.
It never presses Enter for you.
Native Windows insertion requires the current daemon so the Web client can
distinguish cmd from PowerShell.
phone / laptop clipboard ── chosen deployment ──> selected machine
dragged file or screenshot ~/.happy/uploads/terminal/…
│
╰─> shell-quoted path at cursor
Terminal handoffs are capped at 8 MB, transferred in bounded chunks, and shown
with progress/error feedback. Older daemons retain the previous small-file
path; update the CLI and restart the daemon for larger files. Files pass through
the selected deployment on their way to the machine; choose Cloud or self-hosting
according to your environment.
Why choose Very Happy?
| The friction | What carries it for you |
|---|
| “This goal has several independent pieces of work.” | A lead can delegate to Claude Code, Codex, and pi teammates, with progress and submitted results in one team view. |
| “My agents and terminals are scattered across several machines.” | One account sidebar and task board aggregate their sessions and attention state — grouped by project by default (or by tag, or flat), with sessions outside any project grouped by folder; start new work on the machine and agent you choose. |
| “Structured chat is pleasant, but sometimes I need the actual tool.” | Keep SDK-backed Claude and drop into a durable, unmodified agent TTY/TUI when necessary. |
| “I left my desk, so the work stopped being legible.” | A responsive Web/PWA workspace keeps conversations, terminals, files, tasks, notifications, and decisions within reach. |
| “Remote control must fit my operating model.” | Start with Very Happy Cloud for the fastest setup, or deploy the same open-source stack under your control. |
The philosophy is straightforward: stay high-level when that is faster, drop to
the raw machine when it is necessary, and make the interface carry as much
operational overhead as possible. The sections above show the supporting detail:
ordinary text TUIs remain compatible, the command palette preserves keyboard
speed, and bounded file handoff moves a local file to the selected machine
without auto-running a command.
One command to your first machine
On macOS or Linux, the hosted Cloud path can install the CLI, run diagnostics,
open the one-time browser approval, and start the detached daemon in one command:
(
set -eu
vh_installer=$(mktemp)
trap 'rm -f "$vh_installer"' \
EXIT HUP INT TERM
curl -fsSL \
https://veryhappy.dev/install.sh \
-o "$vh_installer"
sh "$vh_installer"
)
The bootstrap still needs Node.js because the CLI and daemon run on Node. If
node or npm is missing, install a supported Node.js release from the
official download page—npm is included—then
run the same command again. The script stops with this guidance instead of
invoking sudo or silently changing the system runtime.
The bootstrap is intentionally boring where trust matters. It:
- verifies a supported Node.js runtime;
- resolves the npm
latest tag once, validates it, and installs that exact
very-happy-cli version;
- runs
very-happy doctor without intentionally reading provider credential
values (review all diagnostic output before sharing it);
- opens the normal short-lived Web approval flow; and
- runs
very-happy daemon start so the machine actually appears online.
The command downloads the complete script to a random temporary file before it
runs and removes it afterward. It never invokes sudo, installs tmux, writes
provider credentials, enables Claude hooks, or hides the trusted-relay warning.
Hosted bytes can change with a Web release: for the auditable path, download the
version-controlled script, compare it,
then run the local file. Its offline no-mutation preview is:
sh ./install.sh --dry-run
The script can connect terminal-based agents without a Claude credential. For
structured Claude, configure a supported provider credential in the daemon's
startup environment. If you add it after the bootstrap has started the daemon,
reload that environment with:
very-happy daemon stop && very-happy daemon start
npm install --global very-happy-cli
very-happy doctor
very-happy auth login
very-happy daemon start
Approve only a machine request you just initiated. Then open
veryhappy.dev, choose the connected machine,
and create your first session.
Machine requirements
| Requirement | Status | Why |
|---|
| Node.js 20.19+ within 20.x, 22.13+ within 22.x, or 24+, with npm | Required | Runs the CLI and daemon |
| Agent provider/runtime | Per agent | Structured Claude uses the bundled Agent SDK plus provider credentials; native terminals and other adapters need their local command or gateway |
tmux | Recommended | Keeps real Web terminals alive across browser disconnects |
tmux 3.2+ | Optional Claude mirror | Provides the create-time environment markers used by terminal → structured handoff |
For the first structured Claude session, configure ANTHROPIC_API_KEY or a
supported Bedrock, Vertex AI, or Foundry environment for the same OS user and
startup environment that runs the daemon. very-happy doctor reports only the
credential source category. See
configuration.
Provider credentials stay local by default. very-happy connect is a separate,
explicit flow that stores a selected OpenAI, Anthropic, or Gemini OAuth
credential on your chosen deployment so Web-launched integrations can use it;
it is currently used primarily by the Gemini path.
Self-hosted first connection
Deploy the relay first, use HTTPS, then keep all three endpoint variables in the
environment that starts the daemon:
export HAPPY_HOME_DIR="$HOME/.very-happy-relay.example.com"
export HAPPY_SERVER_URL=https://relay.example.com
export HAPPY_WEBAPP_URL=https://relay.example.com
npm install --global very-happy-cli
very-happy doctor
very-happy auth login
very-happy daemon start
Use a separate HAPPY_HOME_DIR for each relay. Tokens and machine IDs belong to
the relay that issued them. The supported public self-host path is the pinned
repository Docker build—not the upstream-owned happy-server-self-host npm
package. See Self-hosting.
Upgrading a self-hosted server (2026-10-26, breaking): TRUST_PROXY no
longer accepts a hop count such as TRUST_PROXY=1; the server refuses to
start with one. Set the IP/CIDR your reverse proxy connects from, e.g.
TRUST_PROXY=172.18.0.1. Details in Upgrading.
The bundled Web app now enforces a Content-Security-Policy; if a script your
proxy injects breaks, use CSP_MODE=report-only. Add a Docker log size limit
(Upgrading).
Move at thought speed
The production command palette searches actions, chats, and terminals. Session
search (Command/Ctrl+Shift+F, or the sidebar Search control on a phone)
searches titles, projects and tags plus what was said on every online machine,
then opens the session on the hit. Saved prompts use Command/Ctrl+..
Very Happy preserves terminal muscle memory: on macOS, Ctrl+K/J/N/R stay with
readline and the real TUI. Browser-reserved new/close chords work only where the
platform delivers them to an installed PWA; normal tabs use the explicit
Alt+N and Alt+W fallbacks. See the precise
keyboard and touch reference.
Agent surface
| Adapter | Status | Experience |
|---|
| Claude Code | Shipped · deepest integration | Bundled Agent SDK structured sessions; native Claude TUI; optional Claude-only terminal mirror |
| Codex | Shipped | Dedicated Codex session path plus native terminal access |
| Gemini | Beta · implemented | Agent Client Protocol backend and preset |
| OpenCode | Beta · implemented | ACP-compatible preset over local stdio |
| Custom ACP command | Beta · implemented | Generic runner for a compatible Agent Client Protocol stdio endpoint |
| OpenClaw | Shipped | Its own local gateway adapter—not ACP |
| pi | Shipped · via pi-acp | ACP runner over the external pi-acp adapter: structured chat, Steer into the running turn, question cards, sub-agent cards, permission modes enforced by the Very Happy pi extension, resume after a crash or restart; also Teams and native terminal tools |
| Provider-aware routing | Roadmap | Cross-provider subtask coordination, not a shipped claim |
Agent Client Protocol is distinct from the older Agent Communication Protocol
that shares the ACP acronym. Support for a terminal-backed agent does not imply
structured parity with Claude.
What ships today
- Structured Claude conversations with tool calls, diffs, permissions, usage,
attachments, and resume.
- Real tmux browser terminals with reconnect, scrollback, search, mobile input,
archived sessions, file access, and automatic recovery.
- Projects: the sidebar groups sessions by project, project
sessions start with shared instructions and decisions, and a project page
shows each session's status;
very-happy spawn --project.
- Session search (
Command/Ctrl+Shift+F) across titles, projects, tags and
every online machine's conversation history, opening the session on the hit.
@ file mentions in the message box, and editable drafts: text the agent
writes for you to send can be edited and copied in place, and your next
message hands the final version back to the agent.- A machine file browser with previews for text, Markdown, images, PDFs, and Excel/CSV
worksheets. Download original files (up to 50 MiB), copy text or paths, and pin
clickable previews from agent output to the workspace. Workbook previews run
locally in a browser worker (10 MiB; up to 50 sheets, 500 rows and 100 columns per sheet).
- Clipboard and drag/drop handoff into a target-machine terminal, with an 8 MB
limit, bounded chunking, upload feedback, and quoted-path insertion without
auto-execution.
- Task board, todo-provider commands, notes, notifications, Web Push, and HTTPS
account webhooks that retry transient failures, with delivery counts in
Settings → Diagnostics.
- Custom models and providers per machine and agent: Settings → Models &
providers or Custom… in the model picker writes base URL, API key (or an
env-variable reference) and models into Claude Code / Codex / Gemini / pi's own
config files on that machine, with a masked diff preview, backups and restore;
pi models can carry their context window (
glm-5.3 200k) so the context meter
no longer reads against pi's 128k default
(details).
- Machine web panels: declare noVNC, a browser dashboard or any local page in the
machine's own settings.json and open it from the session workspace or machine
page; agents call
request_human to get a person, and the push opens the panel
(setup).
- A Claude-powered coordinator with text entry, session awareness, and dispatch
on its selected machine; voice entry is available when a compatible voice
service is configured.
Optional Claude terminal mirroring is explicit and reversible:
very-happy install-terminal-hooks
# Remove only Very Happy's entries later:
very-happy install-terminal-hooks --remove
This modifies ~/.claude/settings.json (or
$CLAUDE_CONFIG_DIR/settings.json) without deleting foreign hooks. Normal
SDK-backed Claude sessions do not require it.
MCP handoffs: make local work visible where you are
Very Happy injects a small MCP surface into managed sessions so an agent can do
more than print another line: it can hand text to your browser clipboard, open
a produced file in the Web preview, keep the session title useful, and report
progress. The exact tools deliberately follow the runner:
| Runtime path | MCP tools shipped today |
|---|
| Base managed Claude session | change_title, copy_to_clipboard, open_preview, report_progress, request_human |
| Managed Codex / Gemini / ACP bridge | change_title, copy_to_clipboard, open_preview, report_progress |
| Assistant/meta-agent variant additions | sessions_list, session_read, session_send, session_spawn, session_kill, session_archive, terminals_list, terminal_read, terminal_send, memory_update, journal_append |
User-scoped plain claude, after opt-in | copy_to_clipboard only |
Enable the narrow plain-terminal bridge with:
claude mcp add --scope user very-happy-clipboard -- very-happy mcp
That registration applies to every Claude session for the same OS user, not
only processes inside a Very Happy terminal. It needs the local daemon. The
assistant-only additions can read and mutate sessions, terminals, memory, and
journals; treat that variant and its prompt/tool permissions as a high-privilege
machine control surface. This is not a universal MCP or provider-routing claim.
See the exact integration contracts.
Configure integrations
| Capability | Setup |
|---|
| External Todo list | Add todoProvider to the machine's ~/.happy/settings.json; copy the provider contract and example. |
| Account webhook | Open Settings → Channels, save one HTTPS endpoint, and select completion / permission events. Transient failures are retried up to 3 times; Settings → Diagnostics shows delivered, retried and failed counts. |
| Dispatch other sessions | Select an Assistant machine in Settings → Voice & Assistant, open Assistant (/assistant), and review its high-privilege permission setting. See the Assistant setup. |
| Script / IM adapter | Run very-happy spawn, send and sessions on the daemon machine — start work, message it, then list / read / stop / archive what you started. |
Compose it into a larger agent system
Very Happy is an execution surface, not a closed automation platform. The
coordinator, the roles it dispatches and the policy around them belong in your
adapter; what this project owns is the execution surface underneath. Generic
webhooks plus the CLI's automation commands are that
contract: spawn starts work (with an origin tag, a permission mode and an
agent of your choosing), send continues it, and sessions lets the adapter
see and steer what it started instead of dispatching blind. That is enough to
connect an issue tracker, scheduler, chat system, or a coordinator of your own
without teaching the core about any of them.
The adapter must own sender authorization, fixed workspace policy, deduplication,
rate limits, and least-privilege execution. Incoming messages are input, never
authorization by themselves.
Regional relay behavior and limits
The account/database server can stay central while latency-sensitive terminal
bytes, machine/session RPC, and structured-message delivery use operator-configured regional relays. Each daemon probes
the healthy candidates in parallel and anchors to the lowest measured RTT; the
browser follows that machine assignment with a short-lived, machine-scoped token.
The active relay and browser-to-relay RTT are visible in the terminal header.
This is measured routing, not a GeoIP guess, and relays do not need database
credentials. If discovery or a regional relay fails, current clients fall back
to the compatible control-server path. Self-hosted operators decide which relay
regions exist; hosted PoP availability is an operational fact, not an implied
global SLA. A future WebRTC direct path can use the same transport seam, with
regional relays remaining the fallback.
Structured input is persisted by the session runner before agent execution;
structured output receives its authoritative central id/seq before the relay
push. The control/data server therefore remains the recovery and history source,
while the regional plane shortens live delivery. It does not add token-level
Claude streaming by itself.
The control/data server synchronizes workspace state; the regional plane routes
latency-sensitive machine/session RPC, structured delivery, and terminal traffic. Encrypted
envelopes inherited from Happy remain defense in depth, but the Very Happy server
can recover account keys. Transport/storage encryption does not make the relay
zero knowledge. Read Architecture and
Security.
Direction, not marketing fiction
The roadmap moves toward more agent adapters, provider-aware subtask routing,
task memory beyond today's project instructions and log, and a meta-agent that brings users decisions rather
than activity. The long-term visual concept is a multi-agent virtual office—
possibly pixel-art—where work, handoffs, and requests for attention become
spatially legible.
Those are roadmap concepts, not shipped features. The philosophy already ships:
work anywhere, keep the thread, and reduce the amount of operational state a
human has to hold. See the roadmap.
Run it, understand it, improve it
The production frontend is packages/happy-web-v2. The upstream Expo/Tauri
packages/happy-app is retained as an experimental seed for a possible future
desktop client; it is currently excluded from the pnpm workspace, production,
and the supported Very Happy client/security scope.
Attribution and license
Very Happy is built by Mereithhh (JoJo). Bugs and ideas:
open an issue. In the app,
Settings → About shows the running Web build, the source and the issue link.
Very Happy is a friendly, deeply modified fork of
slopus/happy and retains upstream copyright
and MIT terms. See LICENSE and NOTICE. Claude Code, Codex,
Gemini, OpenCode, OpenClaw, and other named agents are products or projects of
their respective owners. Very Happy is independent and is not affiliated with
them.
Getting started and agent skills
Open Help & getting started in the workspace to connect another computer, choose chat or a terminal, and find Teams, Automations, files and todos. The guide also links the official team installer, Todos → My todos → Let AI use my todos, the Automations skill (very-happy auto skill) and the external todo-provider skill. App-created teams receive their instructions automatically; terminal skill installation does not attach an unmanaged terminal or grant account access.
