Agent hooks and Live Activities

moshi-hook is the companion daemon that lets local coding agents report useful events to Moshi. It runs on your host, installs agent hook config, keeps a local Unix socket for hook calls, and maintains a WebSocket connection back to Moshi for approvals and status updates.

Supported agents

The installer can wire these agents:

• Claude Code.
• Codex CLI.
• OpenCode.
• Gemini CLI.
• Cursor.
• Kimi.
• Qwen Code.

The exact event surface differs by agent, but Moshi normalizes events into a small set of inbox categories.

Install on macOS

Open Settings -> Agent Hooks in Moshi and copy your pairing token. Then run:

$brew tap rjyo/moshi
$brew install moshi-hook
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$brew services start moshi-hook

On macOS, secrets are stored in Keychain by default. If you pair from SSH and Keychain is locked, unlock it first or use file-backed storage:

$security unlock-keychain ~/Library/Keychains/login.keychain-db
$moshi-hook pair --token <token from Moshi>
$moshi-hook pair --token <token from Moshi> --store file

Install on Linux

$curl -fsSL https://getmoshi.app/install.sh | sh
$moshi-hook pair --token <token from Moshi>
$moshi-hook install
$moshi-hook serve

For a permanent Linux setup, run moshi-hook serve under your process manager of choice.

Update

On macOS, refresh the tap and upgrade:

$brew update
$brew upgrade moshi-hook
$brew services restart moshi-hook

On Linux, re-run the install script and restart your moshi-hook serve process:

$curl -fsSL https://getmoshi.app/install.sh | sh

Pairing and installed agent hooks survive an upgrade — no need to re-pair or re-run moshi-hook install.

What install changes

moshi-hook install writes Moshi-owned entries into supported agent config files. It is designed to leave user-owned hooks alone.

Managed locations include:

• Claude Code: ~/.claude/settings.json.
• Codex: ~/.codex/hooks.json and the needed Codex config flag.
• OpenCode: .opencode/plugins/moshi-hooks.ts in the current project.
• Gemini: ~/.gemini/settings.json.
• Cursor: ~/.cursor/hooks.json.
• Kimi: ~/.kimi/config.toml.
• Qwen: ~/.qwen/settings.json.

Use moshi-hook uninstall to remove Moshi-owned entries.

Inbox categories

Moshi forwards a deliberately small set of events:

Moshi's inbox keeps one active row per agent session. New events for the same session update the row instead of creating a long stack of notifications.

Third-party harnesses

Custom harnesses that are not installed through moshi-hook, such as oh-my-pi notification plugins, can use Moshi's compatibility webhook:

curl -X POST https://api.getmoshi.app/api/v1/agent-events \
  -H "Authorization: Bearer $MOSHI_USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "opencode",
    "eventType": "notification",
    "sessionId": "omp-session-1",
    "category": "task_complete",
    "title": "Task complete",
    "message": "oh-my-pi finished a turn",
    "eventId": "omp-event-1"
  }'

Use category values from the table above. approval_required events should include pendingActionId, expiresAt, and hostId only when the harness can also route decisions back to the running host. Host-resident daemons should prefer POST /api/v1/hosts/:hostId/events with the host secret.

Live Activities

Agent events can update the iOS Live Activity and Dynamic Island when Live Activities are enabled in Settings -> Agent Hooks. Approval and error events can also trigger visible push notifications; quieter events can still update the inbox and Live Activity.

The settings screen includes a demo Live Activity button so you can test the lock-screen surface without waiting for a real agent event.

Diagnostics

Useful commands:

$moshi-hook status
$moshi-hook status --json
$moshi-hook logs -f
$moshi-hook usage --sync

If hooks are installed but Moshi does not update, check that moshi-hook serve or the macOS service is running and paired to the same Moshi account/token shown in the app.