joy-hooks

joy

A terminal dashboard for monitoring Claude Code sessions in real-time.

Joy displays all active Claude Code sessions with their current state, project name, and latest message -- like a LINE/Slack unread indicator for your AI coding sessions.

日本語ドキュメント

Install

npm i -g @yumazak/joy

Usage

joy

Joy starts a local HTTP server on 127.0.0.1:50055 and renders a TUI dashboard.

Options

Flag	Description	Default
--port, -p	Port for the HTTP server	50055

Environment Variables

Variable	Description	Default
JOY_PORT	Port used by the hook script	50055
JOY_URL	Full URL for the hook endpoint	http://127.0.0.1:${JOY_PORT}/hooks

Claude Code Hooks Setup

Install the joy-hooks plugin using the Claude Code CLI:

claude plugin marketplace add https://github.com/yumazak/joy
claude plugin install joy-hooks@joy

That's it! The plugin registers all necessary hooks automatically. Hooks silently do nothing when joy is not running, so no error messages will appear.

Session States

State	Indicator	Description
Processing	🔄	Claude is actively working
WaitingApproval	🟡	Waiting for tool use approval
WaitingInput	🟢	Waiting for user input

Hook Events

Event	Maps to State
PostToolUse	Processing
PermissionRequest	WaitingApproval
Stop / UserPromptSubmit	WaitingInput

Development

pnpm install
pnpm run dev      # Start development server
pnpm run test     # Run tests
pnpm run lint     # Run linter

Tech Stack

• Ink - React-based terminal UI
• Hono - HTTP server
• Node.js - Runtime

License

MIT