Reach and resume your AI coding-agent sessions from any browser or phone, served from a machine you own
-2c2c2e?style=flat-square){kind=icon}
Website · Docs · Install · Install guide · Releases · Watch the talk
Hapimatic is a local-first meta-harness for the AI coding agents you already use. It runs your agent sessions on your own machine and serves them to an installable web app, so a full session (chat, tool calls, a real terminal, notifications, and approvals) works from your phone as well as from your desk. Claude Code, Codex, Gemini CLI, and OpenCode are supported at launch; each one is the provider's own unmodified program, signed in with your own account. This repository is the open-source core of Hapimatic, released under the GNU Affero General Public License v3.0.
Sessions, grouped by project
A live session, mid-task
The same session on a phone
Closing the Loop: Hardware Development with Advanced Agentic AI · 29 minutes · 15th Philly Hardware Meetup, Drexel University, October 21, 2026
Matt Starfield, the Senior Electrical Engineer at Solid Product Design, shows how he built Hapimatic one bottleneck at a time, then closes the loop on real hardware with the Hardware Bench, a paid add-on of the hosted service that is not part of this repository: agents that flash firmware onto live boards, drive bench instruments, and prove every fix with a measurement. Every slide and link from the talk is at hapimatic.com/talks/closing-the-loop.
Restarting the Hapimatic server or its background service (the daemon) does not end a running Claude
Code session: it keeps running and stays connected to the web app. With tmux persistence on
(HAPI_TMUX_PERSISTENCE=true), the sessions the daemon starts run inside tmux, and a restarted daemon
takes them back. Gemini CLI and OpenCode sessions are not taken back after a daemon restart. One known
issue: after a server restart, a Claude Code session started from a terminal runs its earlier prompts
again; the install guide describes it and the
workaround.
The same responsive app on your phone, tablet, and desktop, installable as a PWA. There is no separate desktop app, phone app, and website with different features.
Hapimatic runs above the agent CLI you choose instead of replacing it. Claude Code, Codex, Gemini CLI, and OpenCode are supported at launch, and the install guide lists each one's status and how it signs in.
Each session can get its own git worktree, so several agents can work on the same repository, on the same machine, at the same time.
Every session is a full peer, with its own context, tools, and lifecycle. A session can start another session, on this machine or another machine you run, hand it work, and read its results, and the web app lists them all.
Recurring and scheduled events start sessions on a timetable, with controls for overlap, active hours, jitter, and backoff.
The complete record of every session stays saved on your machine. Search it, and recover any session to continue the work, by hand or from another agent.
When an agent needs a judgement or an authorization, Hapimatic tells you by push notification on your phone, or by Telegram with your own bot.
The monorepo has four packages that develop and test independently:
| Package | Role | Stack |
|---|---|---|
cli/ |
The hapi CLI, daemon, launchers, and agent runners |
Bun executable, Vitest |
server/ |
HTTP and WebSocket backend | Hono 4, SQLite (bun:sqlite), Socket.IO, SSE |
web/ |
Installable PWA | React 19, Vite, Tailwind CSS 4, TanStack Router/Query |
shared/ |
@hapi/protocol, the Zod schemas they share |
Zod 4 |
Everything compiles into one executable with the web assets embedded. There are no containers, no ORM, and no cloud dependency. The supported platform is 64-bit Linux (x86-64 or ARM64) with systemd; macOS is planned.
Install your agent CLI and sign in to it first (for Claude Code, run claude once). Then install
Hapimatic with one command:
curl -fsSL https://github.com/SolidPD/hapimatic-core/releases/latest/download/install-hapimatic-v1.sh | bashFor a step-by-step walkthrough, see hapimatic.com/install and the installation guide. The documentation lives on hapimatic.com; this repository does not ship the docs site.
Open a new shell so that hapi is on your PATH, then start the server:
hapi serverOn first run it prints an access token and saves it to ~/.hapi/settings.json. In another terminal, in
your project folder, start a session:
hapi # Claude Code
hapi codex # Codex
hapi gemini # Gemini CLI
hapi opencode # OpenCodeOpen http://localhost:3006 in your browser and enter the access token.
The installer takes a mode after bash -s --, for example
curl -fsSL https://github.com/SolidPD/hapimatic-core/releases/latest/download/install-hapimatic-v1.sh | bash -s -- doctor:
doctorchecks your machine, one line per check, and names anything missing--dry-runshows the install plan without changing anythinguninstallremoves what the installer wrote (add--purgeto also remove the access token and the session database)- Upgrade by running the installer again; it is idempotent, so a second run changes nothing that is already current
The installation guide covers the prerequisites, machine requirements, remote access from your phone, installing the PWA, and starting new sessions from the web app with the daemon. The quick start is the short version.
Hapimatic builds from this repository alone, with no private dependency, token, or network credential. You need Bun, Node 20 or later, and at least one agent CLI.
bun install --frozen-lockfile
bun run dev # web and server dev servers, live reload
bun run build:single-exe # the single-file hapi executable, under cli/dist-exe/
bun run typecheck:cli # also typecheck:server, typecheck:web, typecheck:sharedThis repository is the AGPL-3.0 open core: the hapi CLI, the session server, and the web and PWA
client. Everything you need to build and run Hapimatic yourself from source is here.
The one-command installer also installs a small core toolkit of hooks and guidance from SolidPD/hapimatic-toolkit, a separate MIT-licensed repository.
The hosted onboarding gateway, managed hosting, single sign-on, and premium plugins are separate products and are not part of this repository.
| Where | What is in it |
|---|---|
| hapimatic.com | The project site |
| Docs | The full documentation |
| How it works | The moving parts, in more detail |
| Install the app | Adding the PWA to your phone's home screen |
| FAQ | Common questions |
CONTRIBUTING.md · SECURITY.md |
How to contribute, and how to report a vulnerability |
Hapimatic builds on HAPI, the open-source project by tiann
(tiann/hapi), which credits Happy Coder
(slopus/happy) as its original project; the cli package also
carries code from Happy's MIT-licensed happy-cli. We're grateful
to the people behind both projects for their work.
Hapimatic is an independent project, with thanks and appreciation to HAPI | tiann/hapi and Happy Coder | slopus/happy, whose work made it possible. It is not officially affiliated with tiann/hapi, slopus/happy, or hapi.dev.
Hapimatic is licensed under the GNU Affero General Public License v3.0; see LICENSE. It
is a fork of tiann/hapi, which is itself AGPL-3.0. The cli package
additionally contains code derived from the MIT-licensed happy-cli
(© 2024 Kirill Dubovitskiy); that attribution is carried in cli/NOTICE. Project-level
attribution is in NOTICE.
Under AGPL-3.0 §13, the complete, corresponding source for every released build is published here and
tagged v<VERSION> before or with that build.
Contributions are welcome under a Contributor License Agreement; see CONTRIBUTING.md.
The CLA-signing process is not live yet, so outside pull requests cannot be merged until it is.
This repository is a generated export: changes are reviewed here and then integrated into the canonical
source tree, so they appear in the next release export.
To report a vulnerability, see SECURITY.md. Please do not open a public issue for
security reports.