Jacky CLI

Jacky ships with a command-line interface that lets you control your pet from the terminal. All commands require a running Jacky instance — they send fire-and-forget actions to the desktop app over a local pipe. No tokens, permissions, or configuration are needed for basic commands.

Quick Reference

Speaking & Emoting

jacky say

Make Jacky speak text aloud with voice and show a speech bubble.

jacky say "Build finished successfully!"
jacky say "Don't forget to commit your changes"

jacky emote

Change Jacky's animation state. Common states include: happy, sleeping, dance, thinking, confused, idle, hurt, and more.

jacky emote happy
jacky emote dance
jacky emote sleeping

jacky react_to

Have Jacky react to a piece of text with an AI-generated comment. Requires an LLM provider to be configured.

jacky react_to "The test suite passed with 42 tests"

jacky ask

Send text through Jacky's full agent pipeline (routines, tools, LLM). This is the same pipeline used when you talk to Jacky directly.

jacky ask "What's the weather like?"
jacky ask "Set a reminder for tomorrow at 9 AM"

Moving Jacky

jacky move_to

Walk Jacky to absolute screen coordinates (in pixels). Accepts X,Y or X Y. The target is clamped to the visible screen area.

jacky move_to 800,600
jacky move_to 800 600

jacky move

Walk Jacky a relative distance in pixels from its current position. Valid directions: left, right, up, down, top (same as up), bottom (same as down).

jacky move left 100
jacky move top 200
jacky move right 500

Notifications & Timers

jacky notify

Show a system tray notification without voice. Useful for scripts and automation.

jacky notify "Deployment complete" --title "CI Pipeline"
jacky notify "Donuts have arrived"

jacky timer

Create a countdown timer. Jacky will notify you when the time runs out.

jacky timer 300 --label "Tea is ready"
jacky timer 900 --label "Pasta"

jacky alarm

Create an alarm clock in 24-hour HH:MM format. Supports optional repeat schedules.

jacky alarm 07:30 --label "Wake up" --repeat daily
jacky alarm 18:00 --label "Standup meeting" --repeat weekdays
jacky alarm 14:30 --label "One-time reminder"

Repeat options: none (default), daily, weekdays.

Running Routines

jacky run_routine

Run a routine by its ID. You can pass variables using --var key=value (can be repeated).

jacky run_routine weather --var city="Mexico City"
jacky run_routine bitcoin_price
jacky run_routine my_custom_routine --var name="Alice" --var count=3

Status Check

jacky status

Check if Jacky is currently running and get a JSON status report including pet state, LLM status, TTS status, and version.

jacky status

Example output:

{
  "ok": true,
  "version": "0.3.0",
  "pet_state": "idle",
  "llm_enabled": true,
  "tts_enabled": true
}

Claude Code Integration

Jacky integrates with Claude Code through lifecycle hooks, an MCP tool server, and managed instructions — all set up with a single command.

jacky claude install

One-command setup that does everything:

1. Enables the WebSocket and MCP servers in Jacky's config
2. Grants the necessary permissions
3. Writes lifecycle hooks to Claude Code's settings
4. Injects a managed instructions block into CLAUDE.md
5. Registers Jacky as an MCP server with Claude Code

# 1. Launch the Jacky desktop app
jacky
 
# 2. One-command setup
jacky claude install
 
# 3. Restart Jacky to activate the servers

After running this, Claude Code will automatically trigger Jacky reactions (thinking, working, success, error) and can call Jacky tools via MCP.

jacky claude uninstall

Removes everything: hooks, CLAUDE.md block, and MCP registration.

jacky claude uninstall

jacky claude --doctor

Health check that verifies hooks, CLAUDE.md, IPC, config, permissions, and CLI availability.

jacky claude --doctor

jacky claude mcp install

Register Jacky as an MCP server with Claude Code only (no hooks or config changes).

jacky claude mcp install

jacky claude mcp uninstall

Remove the Jacky MCP server registration from Claude Code.

jacky claude mcp uninstall

jacky claude mcp --doctor

Check MCP-specific health: Claude CLI, registration, and IPC.

jacky claude mcp --doctor

OpenCode Integration

Jacky integrates with OpenCode through a reaction plugin, an MCP tool server, and managed instructions — all set up with a single command.

jacky opencode install

One-command setup that does everything:

1. Enables the WebSocket and MCP servers in Jacky's config
2. Grants the necessary permissions
3. Adds a mcp.jacky remote entry (with auth headers) to OpenCode's config
4. Writes a managed instructions file and references it in OpenCode's instructions
5. Installs the reaction plugin into OpenCode's plugins/ directory

# 1. Launch the Jacky desktop app
jacky
 
# 2. One-command setup
jacky opencode install
 
# 3. Restart Jacky to activate the servers

After running this, OpenCode will automatically trigger Jacky reactions (thinking, working, waiting, success, error) and can call Jacky tools via MCP.

Add --project to configure the current project's .opencode/ directory instead of the global config, or --no-plugin to install MCP tools only.

jacky opencode install --project
jacky opencode install --no-plugin

jacky opencode uninstall

Removes everything: the MCP entry, the instructions reference/file, and the plugin.

jacky opencode uninstall

jacky opencode --doctor

Health check that verifies the MCP entry (including auth headers), instructions file, plugin, IPC, config, and CLI availability.

jacky opencode --doctor

Installing Workshop Content

jacky add

Download and install workshop content (skins, routines, or language packs) from the community portal.

jacky add skin author/skin-name
jacky add routine author/weather-routine
jacky add lang author/spanish-pack

Examples

# Build pipeline notifications
jacky say "Build started"
# ... run your build ...
jacky say "Build finished successfully!" && jacky emote happy
# or on failure:
jacky notify "Build failed" --title "CI" && jacky emote error
 
# Quick timer for cooking
jacky timer 480 --label "Pizza is ready"
 
# Run a weather routine
jacky run_routine weather --var city="Mexico City"
 
# Move Jacky around the screen
jacky move_to 800,600
jacky move left 100
 
# Check if Jacky is running before scripting
jacky status && jacky say "Starting automated tasks"