OpenCode

This page documents how Happier integrates with OpenCode and what matters for day-to-day use.

Requirements

• OpenCode CLI installed on your machine.
• Binary available on PATH as opencode or opencode2 (or set HAPPIER_OPENCODE_PATH).

Choose Auto, Stable, or V2 under Settings → AI & Agents → AI backends → OpenCode. Auto prefers opencode, falls back to opencode2, and detects the server dialect after startup. Stable always selects the released opencode command, but does not assume that command is V1: the server health probe still decides whether Happier uses the V1 or V2 wire contract. V2 prefers opencode2 when installed and otherwise launches the released opencode command with V2 selected. Released OpenCode 2.0.15 provides both command names as aliases, so the name alone does not prove which API version is installed. The same executable selection applies to managed servers, ACP sessions, terminal attach, handoff, and resume helpers.

In current development builds, Happier applies your selected V2 model, reasoning effort, and agent mode before opening the TUI, even before the first message. Standalone attachment asks the running Happier session to apply those controls first; if preparation fails, attachment stops rather than opening with different settings. Keep the attaching CLI and running session on a build that supports this preparation operation.

Install OpenCode

If you use Happier's provider installer, you can install OpenCode from the CLI:

happier install provider opencode
opencode --version

Or install manually:

curl -fsSL https://opencode.ai/install | bash
opencode --version

On Windows, OpenCode also supports native installs such as:

npm install -g opencode-ai
opencode --version

If Happier offers to run OpenCode’s vendor install recipe for you, it requires explicit confirmation before executing vendor install commands.

Local authentication in Happier

OpenCode supports machine-local auth management in:

• Settings → AI & Agents → AI backends → OpenCode

From there you can:

• check whether OpenCode is authenticated on the selected machine
• open opencode auth login directly inside Happier
• refresh the auth state with Check now

Happier reads OpenCode’s local auth state through the CLI’s own auth listing flow when available.

For the shared user guide, see Provider authentication.

How Happier runs OpenCode

OpenCode has two runtime paths in Happier:

• Server-native (default): Happier talks to the OpenCode server/session APIs directly. This is the normal path for new OpenCode sessions in Happier.
• ACP (legacy fallback): still available when you explicitly switch OpenCode to ACP mode.

For most users, the important part is:

• new OpenCode sessions default to the server-native backend,
• Happier can keep the same OpenCode session visible in both the app and the terminal,
• attaching later should use happier attach <session-id>, not a raw vendor attach command.

By default, Happier uses a managed local OpenCode server on the machine and reuses it across sessions. Advanced users can set an explicit OpenCode server URL in settings; when you do that, Happier will keep using that explicit server for the session.

The server-native backend negotiates the installed server's V1 or V2 API over the same authenticated connection. Current development source adapts prompts, permissions, questions, transcript events, session diff, and manual compaction to the selected API. OpenCode 2.0.15 exposes different routes and message shapes from V1; selecting a V2 executable alone is not enough for an older Happier CLI to support it.

Happier registers its MCP tools with both V1 and released V2 server-native sessions. V2 registration uses OpenCode's experimental MCP API; it is not the removed V1 registration route. ACP sessions continue to receive MCP servers through ACP.

When server-native sessions share an OpenCode server, Happier gives each session's injected MCP servers distinct internal names. This keeps one session's tool registration from replacing another's, including when both select different configurations for the same named MCP server. Happier still shows the configured names in its tool timeline; stopping a session disconnects only its own MCP servers.

Released OpenCode 2.0.15 can report a newly registered MCP server as connected before its tools are available to a prompt. Its public API provides no tool-catalog readiness signal. An immediate first tool call can therefore report an unknown tool; the connection status alone does not prove tool readiness. Happier does not hide this upstream race with a fixed startup delay.

Current development source uses the matching connected-account integration for each generation: the callable auth plugin for V1 and a { id, setup } request-hook plugin for released V2. Both use Happier's existing credential broker. Direct OpenAI/Anthropic API keys use V2's provider configuration rather than the removed OPENCODE_AUTH_CONTENT mechanism. These changes are not present in Happier CLI 0.2.12 stable.

Start OpenCode from a terminal

happier opencode

When you start OpenCode this way:

• the session appears in Happier as a normal session,
• the terminal starts in local/shared control,
• the Happier app can still see the same transcript and send messages into the same OpenCode session,
• messages typed directly into the OpenCode TUI also show up in Happier.

This is useful when you want the provider TUI first, but still want the app to stay attached to the same session.

Detach from the app

In current development builds, Happier offers Detach terminal when the session runner owns an attached OpenCode TUI. OpenCode remains shared-control: this is not an exclusive switch away from the app.

Using it:

• keeps the same session id and transcript,
• closes the runner-owned OpenCode TUI while the Happier session keeps running,
• keeps the app writable against the same server-backed session.

A separate happier attach client stays independent. Close it in its own terminal; the app's detach action does not close that client. Its exit also does not detach a different TUI owned by the session runner.

In development builds, a client admitted inside its restored Herdr pane after a server restart is managed instead: Detach terminal closes that native client while preserving the restored shell and the same running OpenCode session. See Attach to a running session for the restoration requirements.

You can later run happier attach <session-id> from a terminal on the same machine to get back into the OpenCode TUI. In current development builds, a session with a terminal host reopens its managed TUI in that existing host; attachment does not merely show the waiting Happier controller or create a second pane.

Start OpenCode from the app

If you start a new OpenCode session from the Happier app:

• without a terminal host selected, Happier starts it in remote/server-only mode in the background,
• the app can use the session immediately,
• no terminal needs to be open yet.

In current development builds, selecting a supported terminal host for new sessions opens OpenCode's TUI there automatically, against the same server-backed session. Selecting no host keeps the background behavior described above.

With OpenCode V2, these builds also apply idle model, reasoning, and agent-mode changes to the running native session without requiring another prompt. With V1, changes are staged for the next prompt sent through Happier; they do not update an already-attached native TUI immediately. Available choices refresh when the server reports catalog changes or reconnects. A discovery failure keeps the last known choices; a successful empty inventory removes them. Choose a model offered by that server: saving an unavailable model in its native session does not make it usable.

Later, on the same machine, you can attach a terminal to that live session with:

happier attach <session-id>

After attaching:

• the terminal shows the OpenCode TUI,
• the app still stays connected and writable against the same session and transcript.

In current development builds, a standalone attach client does not advertise an app-managed detach action unless the controller admits it as a managed restored Herdr client. Close an independent client in its terminal when you are done.

This is the main “start in the app, continue in the terminal” workflow for OpenCode.

Local vs remote control in OpenCode

OpenCode uses shared local control in Happier.

That means:

• Remote mode: Happier drives OpenCode in the background and you use the app/web UI
• Local mode: you use the OpenCode TUI in a terminal
• the transcript stays shared in both modes
• the session stays writable from the app even when a terminal is attached
• app messages do not need the pending-queue handoff used by exclusive local-control paths

In practice, you can:

• send a message from the app and watch it appear in the attached OpenCode TUI,
• send a message from the OpenCode TUI and see it appear in Happier,
• detach and reattach without starting a new session.

For the full switching workflow, see Features → Attach to a running session.

Authentication (connected services)

OpenCode can reuse connected services profiles when spawned by Happier (for example):

• openai-codex (subscription OAuth) or openai (API key) for OpenAI-backed usage
• claude-subscription setup-token profiles or anthropic (API key) for Anthropic-backed usage

If multiple compatible profiles exist, Happier will let you pick one when starting a new session.

OpenCode accepts claude-subscription only for setup-token profiles. Claude subscription OAuth profiles are shown as setup-token action rows and cannot be selected as an OpenCode session binding.

See: Connected services

Session handoff

OpenCode supports Happier session handoff between machines.

This is a natural fit for OpenCode because Happier can move the same Happier session while preserving OpenCode continuity on the new machine.

Use it when you want to:

• move a live OpenCode session from one machine to another
• keep the same Happier session id
• continue the same work from the target machine

Connected services can help here too, especially when the target machine should reuse account-managed credentials instead of depending only on a local machine login state.

See:

• Session handoff
• Connected services

For the full user-facing MCP guide in Happier, see:

• MCP servers

Permissions, modes, and models

Happier uses the same provider-agnostic permission picker for OpenCode as it does for other agents.

Important OpenCode notes:

• permission intent is chosen in Happier,
• Happier maps that intent to the closest OpenCode session permission ruleset,
• some OpenCode behavior still depends on the installed OpenCode runtime.

OpenCode can also expose provider-native session modes and model choices. When those are available, Happier surfaces them in the session UI.

For the full user guide, see:

• Model and engine selection
• Permissions

Managed OpenCode server credential

OpenCode 2 protects every opencode serve with a password: it uses the one supplied in the environment, otherwise it generates a random secret at startup. Happier therefore supplies the password for the OpenCode server it manages for you:

• If you set OPENCODE_PASSWORD (or the legacy OPENCODE_SERVER_PASSWORD), Happier starts the managed server with your password and authenticates with it. Changing it starts a separate managed server, because a server can only serve the sessions that authenticate with its own password.
• Otherwise Happier generates the password for that server, keeps it in the owner-only managed-server state file under ~/.happier/opencode/managed-servers/, and reuses it for health checks, session requests, and terminals it attaches to that server — including after a daemon restart.

The generated password stays on your machine: it is passed to the server through the environment, is never written to Happier's OpenCode server logs, and is never sent to a remote OpenCode endpoint. To talk to the managed server yourself, read the password from that state file, or start the server with your own OPENCODE_PASSWORD.

Notes

• Resume availability is session-specific in Happier: the session must have valid OpenCode resume metadata, and your current backend/settings must allow resume.
• Current development source reconciles exact saved message identities when resuming an existing OpenCode session, so settled native-terminal turns missing from Happier can be recovered without duplicating committed messages. Import identities preserve opaque IDs without delimiter collisions; older import identities require a separate matching native-session identity. If older history lacks provable identities, Happier reports an incomplete-history notice instead of guessing; those older rows may remain missing, while new native turns continue to sync. Failed or malformed history reads are not treated as empty history. These corrections are not available in CLI 0.2.12 stable.
• Attach availability is also session-specific: the session must have the metadata/context Happier needs to reopen that OpenCode session locally.
• Model, mode, and permission behavior can still vary by installed OpenCode runtime.
• Tool events are normalized into Happier’s canonical tool timeline.
• For OpenCode reattach flows, the supported command is happier attach <session-id>.

Troubleshooting

If OpenCode is not detected:

1. Verify opencode --version or opencode2 --version works.
2. Restart Happier.
3. Set HAPPIER_OPENCODE_PATH if your binary is not in PATH.

The session is visible in the app but I want the TUI again

Use:

happier attach <session-id>

Do this on the same machine and against the same Happier account/server profile that owns the session.

The terminal is open but no longer accepts prompts

If Happier detached its managed TUI, the session can still accept messages from the app. Reattach with happier attach <session-id> from a terminal on the same machine.

Related

• Agent capabilities — what this agent supports, generated from the manifest.
• Choosing an agent
• Model and engine selection
• Agent authentication