Claude

This page documents how Happier integrates with Claude Code and what Claude-specific settings do.

Modes: local vs remote

Happier supports two ways of running Claude:

• Local mode: you run Claude Code’s own TUI directly in your terminal.
• Remote mode: you drive Claude from the Happier UI, but Claude still runs locally on your machine (Happier spawns the claude process in the background).

Remote mode currently has two implementations:

• Agent SDK remote (default): uses the official @anthropic-ai/claude-agent-sdk to run Claude, publish capabilities, and (optionally) enable file checkpointing.
• Legacy remote (fallback): our older “SDK-like” shim that spawns claude with a streaming output format and uses a hook-forwarding workaround for session info.

Start in Happier, continue in the terminal

Claude supports Happier’s attach flow for app-started sessions:

• start a Claude session from the Happier app,
• let Happier run it remotely on your machine,
• later reattach with happier attach <session-id>,
• switch into local mode when you want to use Claude Code’s native terminal UI directly.

You can later switch back to remote mode and continue from the Happier app without starting a new session.

On machines with tmux, this is usually a tmux-backed attach flow. On Windows, use Happier’s Windows remote session mode (Windows Terminal, Console, or Hidden) instead of expecting tmux.

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

Permissions and modes

Happier uses:

• a provider-agnostic permission mode (default, read-only, safe-yolo, yolo)
• a separate Claude session mode surface (including Plan)

For the full user guide (CLI flags, UI picker, defaults, and apply timing), see:

• Permissions
• Session modes

Claude plan mode

In current Happier builds, Plan is shown under Mode, not under the normal permission picker.

That matters because:

• Mode = Plan changes Claude’s behavior for the current session
• permission mode still controls how approvals are handled

Plan mode does not bypass approvals by itself. Claude can still ask for permission while the session is in plan mode.

Exiting plan mode

When Claude finishes planning, Happier surfaces Exit Plan Mode as a user-action request.

Common choices are:

• Approve Plan
• Request changes
• Approve Plan (Accept Edits)
• Approve Plan (Bypass All Permissions)

Those choices affect what happens after Claude leaves plan mode:

• Approve Plan returns to normal build mode
• Accept Edits returns to build mode with an edit-friendly permission posture
• Bypass All Permissions returns to build mode with a YOLO-style permission posture

If you request changes, Claude stays in plan mode and revises the plan instead of starting execution.

Local ↔ remote switching

Permission mode is stored canonically in session metadata, so it follows the session when you:

• open the same session on another device, or
• switch between local and remote mode.

Some permission behavior is implemented by Happier (tool approval gating) and can update immediately; other behavior depends on Claude’s own session flags and may only take effect when Claude is launched/resumed. The in-session picker’s “Effective policy” line is the source of truth for what will apply right now.

Install Claude Code

Install and authenticate Claude Code on your machine first, then restart Happier.

Use Anthropic’s official setup guide:

• https://docs.anthropic.com/en/docs/claude-code/getting-started
• https://docs.anthropic.com/en/docs/claude-code/overview

Anthropic currently supports both install paths. Prefer the native installer flow in their docs, and use npm (npm install -g @anthropic-ai/claude-code) when that better fits your environment.

Install via hstack (best-effort)

If you use hstack, you can run the provider installer (uses the upstream native installer by default):

hstack providers install claude
claude --version

Local authentication in Happier

Claude also supports machine-local provider authentication directly in provider settings.

Open:

• Settings → AI provider settings → Claude

From there you can:

• check whether Claude is logged in on the selected machine
• see whether Happier detected CLI login, ANTHROPIC_API_KEY, or ANTHROPIC_AUTH_TOKEN
• open Claude’s native login flow inside Happier
• refresh the auth state with Check now

Happier launches Claude and sends /login for you when you use Log in.

For the shared user guide, see Provider authentication.

Authentication (connected services)

Claude can authenticate through Happier connected services:

• claude-subscription: Claude subscription credentials
  • Setup-token (recommended default): generate on any machine with Claude Code installed via claude setup-token, then paste into Happier
  • OAuth: available through paste redirect flows everywhere and in-app browser on native
• anthropic: Anthropic API key (Anthropic Console)

In the app:

• Settings → Connected services → Claude

In the CLI:

# Claude subscription (recommended default)
happier connect claude --setup-token

# Anthropic API key (not subscription)
happier connect claude --api-key

# Subscription OAuth (advanced)
happier connect claude --oauth

For more details (service ids, security model, and env overrides), see:

• Connected services

Practical guidance:

• Prefer setup-token when you want the most stable Claude subscription credential across machines.
• Use OAuth when the user does not already have Claude Code installed / logged in.
• In the new-session auth picker, Claude-compatible backends will show only the Claude-related connected-service options they actually support.

Session handoff

Claude supports Happier session handoff between machines.

That means you can:

• start a Claude session on one machine
• hand off the same Happier session id to another machine
• continue that session there
• hand it back later if needed

Important notes:

• machine-local Claude login still matters for native Claude CLI workflows
• connected services can make cross-machine continuity easier because the credential is account-managed instead of machine-local only
• direct-session handoff support is provider-dependent, but Claude is one of the supported providers

See:

• Session handoff
• Connected services

Where to configure Claude in Happier

In the app:

1. Settings
2. AI provider settings
3. Claude (remote)

Most settings below affect Claude remote mode only.
The one exception is Experimental: local permission bridge, which affects local mode.

Settings reference (Claude remote)

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

• MCP servers

Environment variables

Happier does not have a Claude-specific “env var” CLI flag. To set environment variables for Claude:

• Local mode: export env vars in your shell before running happier (Claude inherits them).
• Remote mode (from the app UI): set env vars on the profile/session in the UI (Happier forwards them to the spawned Claude process).

Remote Agent SDK mode uses a filtered environment by default, but explicit GUI/profile env vars (and connected-services auth env vars) are forwarded to the Claude subprocess so workflows like GitHub integration can work without leaking the full parent process.env.

Agent Teams (Claude swarms) in Happier

When Agent Teams are enabled in Claude, Happier can:

• Force-enable Agent Teams for all Claude starts (local + remote) via the Force-enable Agent Teams (experimental) setting.
• Route user messages from the main session composer to:
  • a specific team member (1:1), or
  • a team broadcast (team-wide).
• Surface Claude teammates as first-class rows in the session Agents tab, where you can reopen their transcript, launch more teammates into an existing team, and terminate them when needed.
• Reopen teammate work from both the Agents sidebar and the original transcript/tool entry.

For the complete user-facing guide to the Agents sidebar, Subagents, details-pane behavior, and Claude team workflows, see:

• Agents & subagents
• Participant routing & live run messaging

Routing UI (recipient chip)

When a Claude session has an active team, the session composer shows a “To:” recipient chip. Use it to:

• send to the Lead (default),
• pick a specific teammate, or
• pick Broadcast.

Routed messages are stored as a provider-agnostic structured message kind (participant_message.v1) so Happier can render them as a distinct card in the transcript (instead of looking like a normal bubble).

The important user-visible rule is:

• Happier shows the message you typed,
• Happier does not show Claude’s internal prompt rewrite for the routing step.

View-aware default recipient

When you open a focused tool transcript view:

• Task transcripts that contain a teammate spawn event can auto-select that teammate as the recipient (if you haven’t manually picked a different recipient).
• SubAgentRun transcripts auto-select the running execution run as the recipient (while it is running).

If you manually pick a different recipient on that screen, your manual choice wins until you leave/reopen the screen.

Teammate lifecycle in the recipient picker

The recipient picker follows the active Claude team roster.

That means:

• active teammates remain available as recipients,
• Broadcast remains available while the team exists,
• terminated teammates are removed from the active recipient list.

Current limitation: attachments and review comments

Routed messages currently do not support:

• attachments, or
• review comment drafts.

Send those as regular lead messages instead.

Regular non-routed session messages do support Happier attachments.

See: Attachments & image previews

Local permission bridge (experimental)

When Experimental: local permission bridge is enabled:

• You can keep using Claude’s local TUI in your terminal.
• Permission prompts are also available in Happier’s UI, so approvals can be done from the app.
• If the bridge is unavailable, Claude falls back to its normal permission prompt behavior in the terminal.

This is intended to improve local-mode usability when you want to keep session control in the app while still using Claude’s local runtime.

Apply timing: This is a user-level setting that syncs with your account settings. It’s picked up when a local Claude session starts. If you change it while a local session is already running, restart that session (or send any message from the app) for the change to take effect.

Advanced options (JSON): allowlist

The advanced JSON field is intentionally restricted so it can’t break Happier’s control plane (hooks, permissions, session handling).

Currently allowlisted keys:

• plugins
• betas
• maxBudgetUsd
• sandbox
• additionalDirectories
• permissionPromptToolName
• tools
• systemPrompt
• debug
• debugFile
• stderr

All other keys are ignored.

File checkpointing and /rewind

When File checkpointing + /rewind is enabled, Happier captures checkpoint IDs and exposes a rewind command:

• /checkpoints shows captured checkpoint IDs (newest first).
• /rewind <checkpoint-id> --confirm rewinds files to a specific checkpoint.
• /rewind --confirm rewinds files to the most recent captured checkpoint.

Important notes:

• Agent SDK rewind is filesystem-only. It does not delete or rewrite the conversation.
• This is different from Claude Code’s interactive /rewind command in the TUI, which can rewind conversation context and/or files. Happier remote uses the Agent SDK rewind behavior.
• /rewind requires explicit confirmation because it can discard local file edits.
• Checkpointing is remote Agent SDK only and may be slower because it captures/streams checkpoint information.
• If you try to /rewind without checkpointing enabled (or before a checkpoint is captured), Happier will report that no checkpoint is available.

Troubleshooting

“Claude not found”

Make sure Claude Code is installed on your machine, then restart Happier.

“Not authenticated”

Log into Claude Code using its normal login flow, then retry.

You can do that either in your terminal or directly from the Claude provider settings page in Happier.

Settings changes don’t seem to apply

Some remote settings can be applied dynamically, but others require a remote runner restart. If in doubt, stop and restart the remote session after changing settings.