Jacky integrates with Claude Code through three complementary mechanisms:
- Lifecycle hooks — Claude Code fires events as you work; Jacky reacts with emotions and speech automatically.
- MCP tool server — Claude Code can call Jacky tools (speak, notify, emote, run routines, and more) via the Model Context Protocol.
- Managed instructions — A marker block in CLAUDE.md tells Claude Code about Jacky's capabilities.
All three are set up with a single command: jacky claude install.
Quick Start
# 1. Launch the Jacky desktop app
jacky
# 2. One-command setup
jacky claude install
# 3. Restart Jacky to activate the WebSocket + MCP serversThat's it. Claude Code will now trigger Jacky reactions automatically, and can call Jacky tools via MCP.
Restart required: After running jacky claude install, restart the Jacky desktop app so the WebSocket and MCP servers start with the new configuration.
Lifecycle Hooks
How It Works
As you use Claude Code, it fires lifecycle events at key moments. Jacky listens to these events and reacts in real time on your desktop:
| Event | Jacky's Reaction | What It Means |
|---|---|---|
| User submits a prompt | 🤔 Thinking | You sent a prompt to Claude Code |
| Agent starts using a tool | 🔧 Working | Claude Code is executing a tool |
| Agent requests permission | ⚠️ Alerting | Claude Code needs your approval |
| Agent sends a notification | ⚠️ Alerting | Claude Code has a notification for you |
| Agent finishes successfully | 😊 Happy | Task completed without errors |
| Agent finishes with error | 😢 Hurt | Something went wrong |
Throttling
To avoid overwhelming you with reactions during rapid agent activity (e.g. multiple tool calls in quick succession), Jacky applies smart cooldowns:
| Cooldown Type | Duration | Description |
|---|---|---|
| Reaction | 10 seconds | Same reaction won't re-trigger within 10s |
| Speech | 20 seconds | Same speech category won't fire within 20s |
| Permission | 3 seconds | Permission events fire more frequently |
If Jacky seems quiet during intense coding sessions, this is normal — the throttling prevents reaction spam.
MCP Tool Server
Jacky runs a Model Context Protocol server using the streamable HTTP transport, bound to 127.0.0.1 (localhost only) for security.
Available MCP Tools
Once connected, Claude Code can call these Jacky tools:
| Tool | Description |
|---|---|
jacky_say | Speak text aloud with voice and show a speech bubble |
jacky_notify | Show a system tray notification (no voice) |
jacky_emote | Change Jacky's animation/emotion state |
jacky_react_to | Have Jacky react to text with an AI-generated response |
jacky_ask | Send text through Jacky's full agent pipeline |
jacky_run_routine | Run a Jacky routine by ID with optional variables |
jacky_set_timer | Create a countdown timer |
jacky_set_alarm | Create an alarm clock |
jacky_status | Get Jacky's current status (state, LLM, TTS, version) |
jacky_move_to | Walk Jacky to absolute screen coordinates (pixels) |
jacky_move | Walk Jacky a relative distance in pixels (left/right/up/down/top/bottom) |
Security
- The server is bound to localhost only (
127.0.0.1) — not accessible from other machines - Optional Bearer token authentication (stored securely in your OS keyring)
- Allowed actions are configurable — you choose which tools external agents can use
- Error messages are sanitized before reaching the AI agent (no file paths, tokens, or tracebacks leaked)
Managed Instructions (CLAUDE.md)
When you run jacky claude install, Jacky injects a managed block into your CLAUDE.md file that tells Claude Code about Jacky's presence and how to interact with it:
<!-- BEGIN JACKY:MANAGED -->
## Jacky Desktop Pet Integration
Jacky is a desktop pet that reacts to your coding activity in real time.
When you use Claude Code, Jacky will automatically emote and react to
lifecycle events (thinking, working, success, errors).
To control Jacky programmatically, use the `jacky` CLI:
- `jacky say "text"` — make Jacky say something
- `jacky emote happy` — set Jacky's emotion
- `jacky status` — check if Jacky is running
These hooks are managed by `jacky claude`. Do not edit the marker block.
Run `jacky claude uninstall` to remove.
<!-- END JACKY:MANAGED -->Jacky looks for CLAUDE.md in this order:
./CLAUDE.md(current project directory — project-local)~/.claude/CLAUDE.md(global)
The managed block is replaced on re-install (idempotent). Only one block is ever present.
CLI Commands
jacky claude install
One-command setup. Performs all of the following automatically:
| Step | What it does |
|---|---|
| Enable servers | Activates the WebSocket and MCP servers in Jacky's configuration |
| Grant permissions | Enables the necessary permissions for external control |
| Write hooks | Adds Jacky hook entries to Claude Code's settings |
| Write instructions | Injects a managed block into CLAUDE.md |
| Register MCP | Registers Jacky as an MCP server with Claude Code |
jacky claude uninstall
Removes everything: hooks from Claude Code's settings, the managed block from CLAUDE.md, and the MCP server registration.
jacky claude --doctor
Health check that verifies:
- Claude Code hooks are present for all lifecycle events
- CLAUDE.md contains the Jacky managed block
- Jacky desktop app is running
jackyCLI is on your PATH- Configuration has the necessary servers enabled
- Required permissions are granted
jacky claude mcp install
Registers Jacky as an MCP server with Claude Code only (no hooks or config changes). This is called automatically by jacky claude install, but can be run standalone.
jacky claude mcp uninstall
Removes the Jacky MCP server registration from Claude Code.
jacky claude mcp --doctor
Checks MCP-specific health: Claude CLI availability, Jacky MCP registration, and whether the Jacky desktop app is running.
Full CLI Command Reference
Troubleshooting
Jacky doesn't react to Claude Code events
- Run
jacky claude --doctor— check for any issues - Verify Jacky desktop app is running:
jacky status - Restart Jacky after running
jacky claude install - Check that the hooks were written to Claude Code's settings
MCP tools not available in Claude Code
- Run
jacky claude mcp --doctor - Verify Jacky appears in
claude mcp list - Restart Jacky after enabling the MCP server
- Verify the MCP server is running on the expected port
Jacky seems quiet during rapid activity
This is likely throttling — Jacky intentionally limits reaction frequency to avoid spam. Throttle state is persisted locally and resets automatically over time. You can delete the throttle file to reset all cooldowns immediately.
Manual MCP registration
If jacky claude mcp install fails (e.g. claude CLI not on PATH), you can register manually:
claude mcp add --scope user --transport http jacky http://127.0.0.1:9877/mcp