Skip to main content

​
System Requirements

Happy works on macOS, Linux, and Windows with the following minimum requirements.

​
Required Software

  • Node.js: Version 20.0.0 or higher
  • Package Manager: npm, yarn, or pnpm
  • Claude CLI: Installed and authenticated (for Claude mode)
  • Gemini CLI: Installed for Gemini mode (optional)
  • Terminal: Modern terminal emulator with Unicode and emoji support
  • Mobile Device: iOS 14+, Android 8+, or modern web browser

​
Installation Methods

​
Install with npm

The simplest way to install Happy:
npm install -g happy-coder
Verify the installation:
happy --version

​
Update Happy

To update to the latest version:
npm update -g happy-coder

​
Platform-Specific Setup

​
macOS

1
Install Node.js
2
Using Homebrew:
3
brew install node@20
4
Or download from nodejs.org.
5
Install Claude CLI
6
npm install -g @anthropic-ai/claude-code
7
Authenticate Claude:
8
claude login
9
Install Happy
10
npm install -g happy-coder
11
Configure Sleep Prevention (Optional)
12
Happy automatically prevents your Mac from sleeping during active sessions using the caffeinate command. To disable this:
13
export HAPPY_DISABLE_CAFFEINATE=true
Add environment variables to your ~/.zshrc or ~/.bash_profile to make them permanent.

​
Linux

1
Install Node.js
2
Using package manager:
3
sudo apt update
sudo apt install nodejs npm

# Upgrade to Node 20+
sudo npm install -g n
sudo n stable
4
sudo dnf install nodejs npm
5
sudo pacman -S nodejs npm
6
Install Claude CLI
7
npm install -g @anthropic-ai/claude-code
claude login
8
Install Happy
9
npm install -g happy-coder
10
Set Permissions
11
Ensure the Happy binary is executable:
12
chmod +x $(which happy)

​
Windows

1
Install Node.js
2
Download and install from nodejs.org or use package manager:
3
choco install nodejs
4
scoop install nodejs
5
Install Claude CLI
6
npm install -g @anthropic-ai/claude-code
claude login
7
Install Happy
8
npm install -g happy-coder
Windows support is experimental. Some features may require WSL2 for optimal performance.

​
Post-Installation Setup

​
Verify Installation

Check that all components are working: 
# Check Happy version
happy --version

# Check Claude is available
claude --version

# Run diagnostics
happy doctor
The happy doctor command checks:
  • Node.js version compatibility
  • Claude CLI installation and authentication
  • Happy daemon status
  • File permissions and configuration
  • Network connectivity to Happy servers

​
Configure Data Directory

By default, Happy stores data in ~/.happy. To use a custom location: 
export HAPPY_HOME_DIR=/path/to/custom/directory

​
Connect Mobile App

Download the Happy app: Authenticate on first run: 
happy auth login
Choose authentication method:
  • Scan QR code with mobile app, or
  • Open authentication URL in browser

​
Optional Dependencies

​
Gemini Support

To use Happy with Gemini: 
npm install -g @google/gemini-cli
Authenticate with Google: 
happy connect gemini
For Google Workspace accounts, set up a Google Cloud Project: 
happy gemini project set your-project-id
See the Gemini authentication guide for detailed setup.

​
Bun Runtime (Experimental)

Happy can use Bun as an alternative JavaScript runtime: 
curl -fsSL https://bun.sh/install | bash
Use Bun to spawn Claude: 
happy --js-runtime bun

​
Configuration Files

Happy stores configuration in these locations:
FileLocationPurpose
Credentials~/.happy/access.keyAuthentication credentials
Settings~/.happy/settings.jsonUser preferences
Logs~/.happy/logs/Daemon and session logs
Session Data~/.happy/sessions/Active session state
Daemon State~/.happy/daemon.stateBackground service status

​
Environment Variables

Customize Happy behavior with these environment variables:
VariableDescriptionDefault
HAPPY_SERVER_URLCustom server URLhttps://api.cluster-fluster.com
HAPPY_WEBAPP_URLCustom web app URLhttps://app.happy.engineering
HAPPY_HOME_DIRData directory~/.happy
HAPPY_DISABLE_CAFFEINATEDisable macOS sleep preventionfalse
HAPPY_EXPERIMENTALEnable experimental featuresfalse
GEMINI_MODELOverride default Gemini model-
GOOGLE_CLOUD_PROJECTGoogle Cloud Project ID-
Add these to your shell profile (~/.zshrc, ~/.bashrc) to persist across sessions.

​
Troubleshooting

Solution: Ensure npm global bin directory is in your PATH:
# Find npm global bin path
npm config get prefix

# Add to PATH (add to ~/.zshrc or ~/.bashrc)
export PATH="$PATH:$(npm config get prefix)/bin"
Solution: Fix npm global permissions:
# Create npm global directory
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Add to PATH
export PATH=~/.npm-global/bin:$PATH

# Reinstall Happy
npm install -g happy-coder
Solution: Install and authenticate Claude:
npm install -g @anthropic-ai/claude-code
claude login

# Verify installation
claude --version
Solution: Check for conflicts and clean up:
# Stop existing daemon
happy daemon stop

# Clean up runaway processes
happy doctor clean

# Restart daemon
happy daemon start

# Check status
happy daemon status
Solution: Upgrade Node.js to 20.0.0 or higher:
macOS
brew upgrade node
Linux (using n)
sudo npm install -g n
sudo n stable
Windows
# Download from nodejs.org or use package manager
choco upgrade nodejs

​
Uninstallation

To remove Happy from your system:
1
Stop the Daemon
2
happy daemon stop
3
Uninstall the Package
4
npm
npm uninstall -g happy-coder
yarn
yarn global remove happy-coder
pnpm
pnpm remove -g happy-coder
5
Remove Configuration (Optional)
6
rm -rf ~/.happy
7
This will delete all session data, logs, and authentication credentials.

​
Next Steps

Quickstart Guide

Get started with your first Happy session

Authentication

Learn about authentication methods and security

CLI Reference

Explore all available commands

Settings

Customize Happy for your workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us