Quick Start

From a Linux machine to a running session that you can reach from your phone.

Install your agent CLI and set up its access

Hapimatic runs Claude Code, Codex, Gemini CLI or OpenCode under your own accounts. Install the one you use from its provider first, then set up its access:

• Claude Code: run claude once and sign in with your Claude subscription, or run Claude Code sessions on a workspace-scoped Anthropic API key (see API key billing).
• Codex: sign in with codex login, or use an OpenAI API key.
• Gemini CLI: use a Google AI Studio or Vertex AI API key only, never the Gemini CLI's own Google sign-in.
• OpenCode: use an API key for the model provider you use with OpenCode.

Each provider's own terms apply to your accounts and keys. Where the Claude Code, Gemini CLI and OpenCode keys go is in Supported agent CLIs.

Install Hapimatic

Read Installation first for the prerequisites and for what the installer changes on your machine. One command installs Hapimatic:

curl -fsSL https://github.com/SolidPD/hapimatic-core/releases/latest/download/install-hapimatic-v1.sh | bash

Open a new shell afterwards so that hapi is on your PATH.

Start the server

hapi server

On first run, Hapimatic prints an access token and saves it to ~/.hapi/settings.json.

Start a coding session

In another terminal, in your project folder, start a session with the agent CLI you use:

hapi            # Claude Code
hapi codex      # Codex
hapi gemini     # Gemini CLI
hapi opencode   # OpenCode

hapi on its own runs Claude Code in the current folder. Each session shows in the web app.

Open the web app

Open your browser:

http://localhost:3006

Enter your access token to log in.

Open it on your phone

On a phone on the same network, open http://<your-ip>:3006. To add it to your home screen as an app, the phone needs an HTTPS address: see the options in Remote access, which also covers reaching it from outside your network, then Install the app. To start new sessions from your phone, run the background service with hapi daemon start (see Daemon setup).

Machine conventions

A session runs without any further setup. Committing from a session needs a git identity, and GitHub features need gh auth login. These, together with an optional secrets file (only the issue-workflow escalation scripts read it) and the git hooks setting, are described in Portable machine conventions. The installer's doctor reports each one with its fix.

Premium plugins

The premium plugins (issue workflow, project manager and hardware bench) are paid add-ons of Hapimatic Cloud, the hosted service, which is in pilot. They are not part of the open-source core.

Next steps

• Handoff - Switch between your terminal and your phone
• Remote access - Access Hapimatic from anywhere
• Notifications - Set up Telegram notifications
• Install the app - Add Hapimatic to your home screen