Agimi

Your AI agent's eyes on the desktop.

A desktop pet that watches your long-running tasks — AI coding agents, builds, deploys — so you don't have to stare at a terminal waiting. Agimi reacts with animations, sound effects, and notification bubbles when your tasks complete or fail.

Quick Start

npm install
npm run tauri dev

How It Works

Agimi runs an HTTP server on port 19280. Remote agents send events via POST /event, and the pet reacts:

Event	Pet reaction
Stop	Happy animation + sound
StopFailure / PostToolUseFailure	Error animation + sound
PreToolUse / PostToolUse	Typing animation
No events for 5 min	Falls asleep

Test it

curl -X POST http://localhost:19280/event \
  -H "Content-Type: application/json" \
  -d '{"event":"Stop","message":"Build complete!"}'

Or run the full demo: ./test-demo.sh

Claude Code Integration

Add HTTP hooks to your Claude Code settings.json (on the machine running the agent):

{
  "hooks": {
    "Stop": [{
      "hooks": [
        { "type": "http", "url": "http://<your-ip>:19280/event", "async": true }
      ]
    }],
    "PreToolUse": [{
      "hooks": [
        { "type": "http", "url": "http://<your-ip>:19280/event", "async": true }
      ]
    }],
    "PostToolUse": [{
      "hooks": [
        { "type": "http", "url": "http://<your-ip>:19280/event", "async": true }
      ]
    }],
    "PostToolUseFailure": [{
      "hooks": [
        { "type": "http", "url": "http://<your-ip>:19280/event", "async": true }
      ]
    }],
    "UserPromptSubmit": [{
      "hooks": [
        { "type": "http", "url": "http://<your-ip>:19280/event", "async": true }
      ]
    }]
  }
}

Replace <your-ip> with your Tailscale IP or localhost if agent and pet run on the same machine.

Security

The HTTP server listens on 0.0.0.0:19280 with no authentication. This is by design — Tailscale or an SSH tunnel provides the security layer.

Do not expose port 19280 to the public internet. Use Tailscale or SSH reverse tunnel only.

Codex CLI Integration

Codex CLI exposes a single stable hook today ([notify], fires when the agent finishes). Run the one-shot setup script — it auto-installs the notify hook into ~/.codex/config.toml and writes a small forwarder script to ~/.codex/agimi-notify.sh:

curl -s http://<your-ip>:19280/setup | bash

Pre-tool / post-tool parity with Claude Code awaits Codex's hook system maturing upstream. The setup script also configures Claude Code hooks if ~/.claude/ exists.

Copilot CLI Integration

Copy hooks/copilot-hook.sh to your Copilot CLI hooks directory. Set AGIMI_HOST and AGIMI_PORT environment variables.

Gemini CLI Integration

Copy hooks/gemini-hook.sh to your Gemini CLI hooks directory. Set AGIMI_HOST and AGIMI_PORT environment variables.

Telegram Fallback

When Agimi is offline (Windows asleep), events can fall back to Telegram. See hooks/fallback-notify.sh. Set TELEGRAM_TOKEN and TELEGRAM_CHAT environment variables, then use as a dual-hook:

{
  "hooks": {
    "Stop": [{ "hooks": [
      { "type": "http", "url": "http://<tailscale-ip>:19280/event", "async": true },
      { "type": "command", "command": "~/.agimi/hooks/fallback-notify.sh", "async": true }
    ] }]
  }
}

Configuration

Config file: ~/.agimi/config.json (created on first run)

{
  "port": 19280,
  "skin": "orange-tabby",
  "size": 128,
  "position": { "x": 100, "y": 100 },
  "volume": 0.7,
  "sound_enabled": true
}

Skins

Right-click the pet or use the system tray to switch between skins:

• Orange Tabby (default)
• Ragdoll

Sound

Plays game sounds on state transitions (requires sound files in ~/.claude/sounds/):

• Happy → BOTW_Yahaha.mp3
• Error → Civ5_Declare_a_War.mp3
• Typing → RDD_Stinger_soft.mp3

Updates

Agimi checks for new releases on startup and silently downloads them in the background. When the download finishes, a sticky notification appears — click it to restart into the new version. Updates are signed and pulled from GitHub Releases.

License

MIT