Not-Happy-Jan

Multi-sensory feedback for AI coding agents: hold music while your agent works, then a local voice — cheerful on success, furious on failure — plus a buzz or flash on devices you already own.

"Not happy, Jan — the issue is…"

📖 Read the docs · 🎬 Watch the demo · 🚀 Quick start

⚠️ Public alpha — early and for fun, with rough edges. Open an issue or start a discussion.

Install

curl -fsSL https://raw.githubusercontent.com/guruswami-ai/not-happy-jan/main/install.sh | bash

One non-interactive command, no sudo. Requirements: Python 3.10+, about 8 GB RAM (16 GB recommended) and, for the default profile, about 5 GB disk. The full live-voice experience runs on Apple Silicon or Linux with an NVIDIA GPU; the minimal profile speaks from the bundled voice bank on any supported Mac or Linux box.

→ Compare them in Requirements & tiers and Install profiles. Linux or NVIDIA host? Start with the Linux guide. Nothing plays? The Quick start has the first checks (nhj voices, nhj devices, nhj status).

Related MCP server: @zeph-to/mcp-server

60-second quick start

nhj test ok                       # hear/feel/see a “done” on every configured channel
nhj voices                        # meet Jan, Bazza and Karren
nhj set jan.ockerism 11           # tune a character live — or just ask your agent
nhj mode rave                     # try a one-word mode; `nhj status` shows where you are

What you'll experience

• 🎷 Hold music while the agent works, pausing when it finishes — a zero-attention working/done signal.

• 👩 Jan says “all done”, 🧑‍💼 Bazza escalates warnings, and 📣 Karren takes over when it breaks.

• 📟 More than speakers: alerts can fan out to a haptic mouse, pixel clocks, a LaMetric, a Vestaboard or a physical bell.

• 🧭 Many agents, still legible: alerts name the session, several coding CLIs are supported, and voice can be enabled per project.

Documentation

Start at the docs site, or jump by intent:

• New here: What is NHJ? · Quick start · Watch the demo

• Choosing or installing: Requirements & tiers · Install profiles · Linux guide

• Living in it: Characters & dials · Modes · Audio & hold music · Generative music

• Wiring agents and devices: Integration · Other agent CLIs · Multi-agent orchestration · Devices · AWTRIX display · Haptic mouse

• Scripts and customising: nhj run for scripts & cron · Dynamic voices · Configuration

• Building on it: Architecture · Developer guide · Contributing

Security & privacy

Inference runs on your machine; cloned-voice references do not leave it. Local services bind to 127.0.0.1 by default, LAN access is opt-in, a secret guard can scan prompts for leaked credentials, and install/uninstall are reversible user-only operations. See SECURITY.md.

Credits & license

Built on the agent-feedback idea from AgentVibes by Paul Preibisch — and taken way too far. Live voices use Qwen3-TTS via mlx-audio on Apple Silicon, or audio.cpp on Linux/NVIDIA.

Code is MIT. Media and voice assets are licensed separately with mixed provenance; see Media provenance and only use voice references you own or have documented consent to use.