This is a fork of Happy Coder, maintained with a focus on orchestrating Claude Code instances. Expect more frequent feature additions and bug fixes relative to upstream.
🌿 Worktrees — isolated branch sessions with AI-assisted merge
| Feature | What it does |
|---|---|
| Git worktree sessions | New session type that creates an isolated git worktree branch; agent works there while other sessions continue on main |
| Worktree session grouping | Worktree sessions appear under their base repo group in the session list, not as separate isolated groups |
| Branch name as title | Worktree sessions show the branch name (e.g. bold-aurora) as subtitle; slightly smaller title keeps them visually distinct |
| Merge button in header | Git-merge icon in the chat header navigates directly to the merge screen for any worktree session |
| Agent-delegated merge | "Merge with AI" dispatches a single prompt; agent handles spec checks, conflict resolution, conventional commit message, and squash merge |
| Return-to-merge banner | Blue pill in session view when navigated from the merge screen; tap to return once the agent signals completion |
🤖 Claude Code — OpenSpec toolbar, model controls, and session defaults
| Feature | What it does |
|---|---|
| OpenSpec inline toolbar | Mode buttons (Explore, Patch, Apply, FF) shown inline on wide layouts (≥640px) with a vertical divider before model controls; submenu preserved on narrow screens |
| Emoji from content | Chat title emoji reflects actual subject matter, not the OpenSpec command prefix used to trigger it |
| OpenSpec submenu | Explore, Patch, Open Panel in one toolbar menu; active mode shown as icon + label |
| Yolo permission default | New sessions default to bypassPermissions/yolo; green/red indicator |
| Inline model & effort toggles | [Snt|Ops] and [Std|1M] pickers replace gear icon; effort shown as chevrons |
| Bedrock model support | bedrock-claude-* variants in model pickers for Bedrock gateways |
| Model & effort from settings | CLI reads ~/.claude/settings.json and surfaces defaults to the app |
| Slash command autocomplete | Typing / surfaces recently-seen commands from past sessions |
| OpenSpec panel | In-app panel with active changes, task progress bars, and toolbar badge |
| Explore & Patch mode | One-shot prefix toggles for /opsx:explore and /opsx:patch |
🧠 Codex — continuity, recovery, and cross-device state
| Feature | What it does |
|---|---|
| Continuity across reconnects | Joyful now persists Codex provider lineage across reconnects so active chats are less likely to restart from scratch |
| Archived Codex resume | Archived Codex sessions can fork forward into a new Joyful session using stored provider identifiers |
| Cross-device mode sync | Codex model, effort, and permission choices stay aligned between UI metadata and outgoing messages, reducing accidental restarts when switching devices |
| Recovery & transcript replay | Joyful can recover from stale or interrupted Codex sessions and fall back to transcript replay when provider continuity is no longer safe |
| Session diagnostics | Session info now shows Codex session/conversation IDs and continuity notes to make reset behavior visible instead of opaque |
| Codex session browser | yarn codex:sessions lists, inspects, resumes, and forks Codex sessions that do not show up in the default picker |
📋 Sessions — resume, browse, archive, and persist state
| Feature | What it does |
|---|---|
| Model & effort persistence | Selected model/effort saved per session, survives restarts |
| Interactive filesystem browser | Navigate remote directory tree in path picker, with hidden-dir toggle |
| Native session browser | Discover and resume existing Claude sessions from ~/.claude/projects/ |
| Split FAB for session resume | Dedicated Resume entry alongside New Session; pick machine, dir, and session |
| Archived sessions | Inactive sessions in a collapsible "Archived (N)" header, collapsed by default |
🎨 UI & UX — session list, density, avatars, and layout
| Feature | What it does |
|---|---|
| Experiments always enabled | Experimental features now stay on by default; the old toggle has been removed |
| Serialized live session updates | Session and message updates are applied in order, reducing missing or out-of-order chat state during reconnects |
| Project group session list | Sessions grouped by project with collapsible headers; state persisted per device |
| Stable session order | Active sessions within a project group stay in creation-date order rather than jumping on each activity update |
| Stable group ordering | Group order persisted; reorder modal (≡) to move groups up/down |
| + button per group | Tap + on a group header to open new-session screen pre-filled for that project |
| Archive in chat header | Archive icon in the chat header to archive active session in place |
| Compact session rows | No per-row avatar/path; reduced heights; single avatar in group header |
| Emoji session titles | Claude prefixes auto-generated session titles with a relevant emoji |
| Status dot on right | Status indicator moved to row right; text label removed |
| Git history & branches | Tappable branch pill shows all branches (ahead/behind) and last 30 commits |
| Plasma avatar style | Gaussian-blurred triadic blobs with screen blending; CSS fallback for web |
| Plasma avatar web fix | clip-path: circle() on the web plasma container ensures blurred blobs are always clipped to a circle; filter:blur() children bypassed overflow:hidden in browsers |
| Condensed density & dark mode | Tighter rows/items; dark surfaces aligned to iOS palette |
| Mobile layout fixes | Code block wrapping, keyboard-anchored overlays, PWA safe-area |
| Machines panel collapsed | Collapse state persisted; defaults to collapsed |
📊 Monitoring — quota, memory, and polling
| Feature | What it does |
|---|---|
| Claude quota widget | 5h/7d rolling-window utilization bars, reset countdown, manual refresh |
| Machine memory stats | Daemon reports total/free RAM + RSS; shown in collapsible sidebar panel |
| Quota polling fixes | Skips API-key-only machines; fixed re-entrant loop causing daemon OOM |
🎙️ Voice — self-hosted ElevenLabs
| Feature | What it does |
|---|---|
| Self-hosted ElevenLabs | Agent ID configurable in Settings → Voice; clear errors when unconfigured |
⚡ Performance & Infrastructure — reconnect, streaming, and daemon co-existence
| Feature | What it does |
|---|---|
| Local agent binary discovery | The daemon is better at finding locally-built Claude/Codex binaries in from-source setups |
| Reconnect batching | Single batch request on reconnect instead of one per session (~92% fewer) |
| Streaming seq fix | Batched seq allocation eliminates gaps that caused slow REST fallback |
| Socket.IO polling fallback | ['polling', 'websocket'] fixes connections behind restrictive networks |
| Happy daemon co-existence | Runs independently alongside existing happy/happier daemons |
| Full rename | All identifiers, env vars, home dirs updated from happy/handy to joyful |
Note: This is a fork — the CLI has not been published to npm. You need to run everything from this repository.
Prerequisites: Node.js 20+, Yarn 1.22.22, and Claude Code installed.
# 1. Clone and install dependencies
git clone https://github.com/datori/joyful.git
cd joyful
yarn install
# 2. Build the CLI
yarn workspace joyful build
# 3. Start the local server + daemon (handles migrations automatically)
yarn dev:stack:start
# 4. Get your seed to link the web app
yarn dev:stack:seedyarn dev:stack:start only starts the local server and Joyful daemon. The Expo web UI is a separate process and should be started in its own terminal:
# In a separate terminal — starts Expo web on http://localhost:8081
yarn dev:stack:webOpen http://localhost:8081 → Settings → Restore with Secret Key → paste the base32 seed printed by yarn dev:stack:seed.
Running the CLI:
# Run against the local dev stack
JOYFUL_HOME_DIR=~/.joyful-dev JOYFUL_SERVER_URL=http://localhost:3007 yarn cli
# Or use the built binary directly
JOYFUL_HOME_DIR=~/.joyful-dev JOYFUL_SERVER_URL=http://localhost:3007 ./packages/joyful-cli/bin/joyful.mjsDev stack commands:
yarn dev:stack:start # Start server + daemon
yarn dev:stack:web # Start Expo web UI on localhost:8081
yarn dev:stack:stop # Gracefully stop everything
yarn dev:stack:status # Show what's running
yarn dev:stack:nuke # Full reset: wipe DB, re-bootstrap, restart
yarn dev:stack:seed # Print seed in base64url and base32 formats
⚠️ PGlite warning: Neverkill -9the server — it uses an embedded WASM database that corrupts on hard kills. Always useyarn dev:stack:stop.
ℹ️ Expo web note: if Expo claims port
8081is already in use buthttp://localhost:8081is not responding, the previous web process likely exited without cleaning up Expo's local state. Start the UI again withyarn dev:stack:web; if the problem persists, stop the stale Expo process and rerun the same command.
# from repository root
yarn release# Instead of: claude
# Use: joyful
joyful
# Instead of: codex
# Use: joyful codex
joyful codex
On your computer, run joyful instead of claude or joyful codex instead of codex to start your AI through our wrapper. When you want to control your coding agent from your phone, it restarts the session in remote mode. To switch back to your computer, just press any key on your keyboard.
- 📱 Mobile access to Claude Code and Codex - Check what your AI is building while away from your desk
- 🔔 Push notifications - Get alerted when Claude Code and Codex needs permission or encounters errors
- ⚡ Switch devices instantly - Take control from phone or desktop with one keypress
- 🔐 End-to-end encrypted - Your code never leaves your devices unencrypted
- 🛠️ Open source - Audit the code yourself. No telemetry, no tracking
| Chat session | Settings |
|---|---|
 |
 |
| Mobile view | Welcome |
|---|---|
 |
 |
- Joyful App - Web UI + mobile client (Expo)
- Joyful CLI - Command-line interface for Claude Code and Codex
- Joyful Agent - Remote agent control CLI (create, send, monitor sessions)
- Joyful Server - Backend server for encrypted sync
We're engineers scattered across Bay Area coffee shops and hacker houses, constantly checking how our AI coding agents are progressing on our pet projects during lunch breaks. Joyful Coder was born from the frustration of not being able to peek at our AI coding tools building our side hustles while we're away from our keyboards. We believe the best tools come from scratching your own itch and sharing with the community.
- Documentation Website - Learn how to use Joyful Coder effectively
- CONTRIBUTING.md - Development setup including iOS, Android, and macOS desktop variant builds
- Edit docs at github.com/slopus/slopus.github.io - Help improve our documentation and guides
MIT License - see LICENSE for details.