relay_url = "https://relay.example.com"

<div align="center">

<h1>Happy Agent</h1>

<h3>The best of Pi, Codex, Claude Code, Kimi Code, and Grok Build — unified in one coding-agent harness.</h3>

<p>
  Use model-native prompts and tools with provider access already configured on
  your machine. Happy Agent adds no account or subscription of its own, never pools or
  resells provider access, and leaves provider terms and limits in force. 
  
  Built by the authors of
  <a href="https://github.com/slopus/happy">Happy</a> and
  <a href="https://github.com/slopus/happy2">Happy 2</a>.
</p>

https://github.com/user-attachments/assets/99a7dee6-36ef-4110-95b2-e236633640a4

<p>
  <a href="#quick-start">Quick start</a> ·
  <a href="#why-happy-agent">Why Happy Agent?</a> ·
  <a href="#how-happy-agent-compares">Compare</a> ·
  <a href="#configuration">Configuration</a> ·
  <a href="DEVELOPMENT.md">Development</a>
</p>

</div>

Happy Agent is an open-source coding-agent harness built on top of
[Pi](https://github.com/earendil-works/pi)'s foundations. It recreates the best
parts of [Codex](https://github.com/openai/codex),
[Claude Code](https://code.claude.com/docs/en/overview),
[Kimi Code](https://code.kimi.com), and
[Grok Build](https://github.com/xai-org/grok-build) in one consistent local
runtime: the right prompts and tools for each model, useful defaults, safe
execution, durable sessions, subagents, MCP, and a friendly terminal interface.

Happy Agent is the headless daemon: it owns agents, tools, permissions, durable
state, and the public API. Happy Terminal is its official TUI. The `happy` CLI
integrates that TUI, Happy Desktop can host it, and any Node.js application can
embed the same `@slopus/happy-terminal` package.

## Quick start

### Step 1: Choose a client

Use `happy` when Happy CLI is installed:

```sh
happy
```

Or install Happy Terminal directly:

```sh
npm install -g @slopus/happy-terminal
happy-terminal
```

### Step 2: Sign in to the agents you want to use

Happy Agent does not have another account to create. Run the coding agents you want and
complete their normal sign-in:

```sh
codex
claude
kimi login
grok login
```

Happy Agent then uses the credentials already managed by those installations. The daemon
checks local credential presence when it starts without contacting provider
servers. Restart the daemon after a new login so the provider enters the model
catalog. Once enabled, Kimi and Grok credential rotations are hot-reloaded from
their local auth stores without copying tokens into Happy Agent.

### Step 3: Start building

```sh
cd your-project
happy-terminal
```

Ask for what you want in plain English. Happy Agent can inspect the repository, edit
files, run commands, delegate work, and verify the result. Use `/model` at any
time to choose an available model.

### Optional: Connect Happy mobile

Happy synchronization is enabled by default in the Happy Agent daemon. Disable it machine-wide in
`~/Happy/Config/happy.toml` on macOS or `~/happy/config/happy.toml` on Linux,
then restart the daemon:

```toml
[settings]
happy_integration = false
```

Repository `happy.toml` files cannot enable or disable this machine-level
integration. When enabled, Happy Agent automatically imports newer credentials from
`~/.happy` when its daemon starts. Desktop and other API clients can read the
current integration status, subscribe to connection updates, and start pairing
through the daemon API; the start response includes opaque `happy://` data to
render as a QR code. Clients can also cancel pairing, unlink this daemon, or
deliberately re-pair it. Happy is available alongside onboarding in desktop
bootstrap, but remains optional and never blocks onboarding completion. To
authenticate from the standalone terminal client, run:

```sh
happy-terminal happy auth
```

Scan the QR code with Happy. Terminals with Kitty or iTerm2 image support show
a PNG QR code; other terminals get Happy's compact text QR. Every primary Happy Agent
session you open is then synchronized live with Happy. Mobile messages enter
the same session and permission boundary as terminal messages; there is no
separate local/remote control mode.
Happy can also send encrypted image attachments, stop the active turn, and
select any provider-qualified Happy Agent model and supported reasoning level.

## Why Happy Agent?

Pi is a wonderfully small, flexible foundation. Codex, Claude Code, Kimi Code,
and Grok Build each add excellent model-specific behavior, but they expose different
tools, permissions, session models, and integration protocols. Happy Agent brings those ideas together
without making you rebuild the setup for every model, machine, or repository.

- **Feels native to the model.** GPT receives Codex-style prompts and tools;
  Claude receives Claude Code-style prompts and tools; Kimi receives its coding
  prompt and Chat Completions contract; Grok receives the open-source Grok Build
  prompt and tool contracts.
- **One dependable workflow.** Sessions, permissions, MCP, Docker, bac

... (truncated)