{"_id":"@ag9898/buddy","_rev":"3-f299dca070fb610ea473cc7643e5c59a","name":"@ag9898/buddy","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.1":{"name":"@ag9898/buddy","version":"1.0.1","keywords":["buddy","desktop-pet","electron","codex","claude-code","wsl"],"author":{"name":"AG9898"},"license":"MIT","_id":"@ag9898/buddy@1.0.1","maintainers":[{"name":"ag9898","email":"aden219898@gmail.com"}],"homepage":"https://github.com/AG9898/buddy#readme","bugs":{"url":"https://github.com/AG9898/buddy/issues"},"os":["win32","linux"],"bin":{"buddy":"out/cli/index.js"},"cpu":["x64"],"dist":{"shasum":"04cb648372c12ef60f5b34e05462770b7b9a898d","tarball":"https://registry.npmjs.org/@ag9898/buddy/-/buddy-1.0.1.tgz","fileCount":23,"integrity":"sha512-CQgcjpR4lVm3ZZPfn71Xl958Rfl2NziUKQI6W9k10jRvdC8vYC9frQ1tpIQG2eaC8yg4LjS3A+XNcxxrjb0Q9g==","signatures":[{"sig":"MEUCIEZ5I1mvIvU6rDGr5utvrs5wb+nsYjxZ2O9HdGzomfAZAiEAqD77IjmI5tXyMzSyfPuFLozxQ2zJII56bO4c+TbQGNw=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":4044243},"main":"out/main/main.js","engines":{"node":">=18"},"gitHead":"3d5e356d1cf5342a3a5d28db281af1f496a1008c","private":false,"scripts":{"dev":"electron-vite dev","lint":"svelte-check --tsconfig ./tsconfig.json && tsc --noEmit -p tsconfig.node.json","test":"vitest run","build":"npm run build:app && electron-builder","prepack":"npm run build:app","test:e2e":"playwright test","build:app":"electron-vite build && vite build --config vite.cli.config.ts","typecheck":"tsc --noEmit -p tsconfig.node.json && svelte-check --tsconfig ./tsconfig.json","test:watch":"vitest","test:coverage":"vitest run --coverage","build:win:local":"npm run build:app && electron-builder --win --config.win.signAndEditExecutable=false --publish never"},"_npmUser":{"name":"ag9898","email":"aden219898@gmail.com"},"repository":{"url":"git+https://github.com/AG9898/buddy.git","type":"git"},"_npmVersion":"11.6.2","description":"Windows floating desktop pet for Codex CLI and Claude Code","directories":{},"_nodeVersion":"24.12.0","dependencies":{"commander":"^12.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.0.0","svelte":"^5.0.0","vitest":"^2.0.0","electron":"^35.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","svelte-check":"^4.0.0","electron-vite":"^3.0.0","@playwright/test":"^1.50.0","electron-builder":"^25.0.0","@vitest/coverage-v8":"^2.0.0","@sveltejs/vite-plugin-svelte":"^5.0.0"},"optionalDependencies":{"electron":"^35.0.0"},"_npmOperationalInternal":{"tmp":"tmp/buddy_1.0.1_1784326357108_0.5335416433563003","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@ag9898/buddy","version":"1.0.2","keywords":["buddy","desktop-pet","electron","codex","claude-code","wsl"],"author":{"name":"AG9898"},"license":"MIT","_id":"@ag9898/buddy@1.0.2","maintainers":[{"name":"ag9898","email":"aden219898@gmail.com"}],"homepage":"https://github.com/AG9898/buddy#readme","bugs":{"url":"https://github.com/AG9898/buddy/issues"},"os":["win32","linux"],"bin":{"buddy":"out/cli/index.js"},"cpu":["x64"],"dist":{"shasum":"22166f70942178856939fdb23e1a15750be440ea","tarball":"https://registry.npmjs.org/@ag9898/buddy/-/buddy-1.0.2.tgz","fileCount":23,"integrity":"sha512-DlcTjbnh+BtoxqpHX6w5DxPBuffS9uUlOjO2NISImL5hLdNJkSRF3I6Tqcv7fQ8ToJDzOycod5M8sa8cpgvvzg==","signatures":[{"sig":"MEUCIE+MBXG0Q76z4lsdkwSTzzPBNpsy3ax+OwD+N9Z7ZyWuAiEApiMb0zJuGIQLLSPK0OUpP2iuvrR91J3yprpCAPKocr0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":3772800},"main":"out/main/main.js","engines":{"node":">=18"},"gitHead":"d5e9e0fa941a24a68a972daf88e8b4d8a2a41381","private":false,"scripts":{"dev":"electron-vite dev","lint":"svelte-check --tsconfig ./tsconfig.json && tsc --noEmit -p tsconfig.node.json","test":"vitest run","build":"npm run build:app && electron-builder","prepack":"npm run build:app","test:e2e":"playwright test","build:app":"electron-vite build && vite build --config vite.cli.config.ts","typecheck":"tsc --noEmit -p tsconfig.node.json && svelte-check --tsconfig ./tsconfig.json","test:watch":"vitest","test:coverage":"vitest run --coverage","build:win:local":"npm run build:app && electron-builder --win --config.win.signAndEditExecutable=false --publish never"},"_npmUser":{"name":"ag9898","email":"aden219898@gmail.com"},"repository":{"url":"git+https://github.com/AG9898/buddy.git","type":"git"},"_npmVersion":"10.9.7","description":"Windows floating desktop pet for Codex CLI and Claude Code","directories":{},"_nodeVersion":"22.22.2","dependencies":{"commander":"^12.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^6.0.0","jsdom":"^25.0.1","svelte":"^5.0.0","vitest":"^2.0.0","electron":"^35.0.0","typescript":"^5.7.0","@types/node":"^22.0.0","svelte-check":"^4.0.0","electron-vite":"^3.0.0","@playwright/test":"^1.50.0","electron-builder":"^25.0.0","@vitest/coverage-v8":"^2.0.0","@testing-library/svelte":"^5.2.8","@sveltejs/vite-plugin-svelte":"^5.0.0"},"optionalDependencies":{"electron":"^35.0.0"},"_npmOperationalInternal":{"tmp":"tmp/buddy_1.0.2_1784837918384_0.49461729536435084","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@ag9898/buddy","version":"1.0.3","description":"Windows floating desktop pet for Codex CLI and Claude Code","main":"out/main/main.js","bin":{"buddy":"out/cli/index.js"},"scripts":{"dev":"electron-vite dev","build":"npm run build:app && electron-builder","build:app":"electron-vite build && vite build --config vite.cli.config.ts","build:win:local":"npm run build:app && electron-builder --win --config.win.signAndEditExecutable=false --publish never","lint":"svelte-check --tsconfig ./tsconfig.json && tsc --noEmit -p tsconfig.node.json","typecheck":"tsc --noEmit -p tsconfig.node.json && svelte-check --tsconfig ./tsconfig.json","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","test:e2e":"playwright test","prepack":"npm run build:app"},"dependencies":{"commander":"^12.0.0"},"optionalDependencies":{"electron":"^35.0.0"},"devDependencies":{"@playwright/test":"^1.50.0","@sveltejs/vite-plugin-svelte":"^5.0.0","@testing-library/svelte":"^5.2.8","@types/node":"^22.0.0","@vitest/coverage-v8":"^2.0.0","electron":"^35.0.0","electron-builder":"^25.0.0","electron-vite":"^3.0.0","jsdom":"^25.0.1","svelte":"^5.0.0","svelte-check":"^4.0.0","typescript":"^5.7.0","vite":"^6.0.0","vitest":"^2.0.0"},"license":"MIT","author":{"name":"AG9898"},"homepage":"https://github.com/AG9898/buddy#readme","repository":{"type":"git","url":"git+https://github.com/AG9898/buddy.git"},"bugs":{"url":"https://github.com/AG9898/buddy/issues"},"keywords":["buddy","desktop-pet","electron","codex","claude-code","wsl"],"engines":{"node":">=18"},"os":["win32","linux"],"cpu":["x64"],"private":false,"publishConfig":{"access":"public"},"_id":"@ag9898/buddy@1.0.3","gitHead":"4ac2428e46ff40505d61df15afbe07252b334902","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-lwhlVwXiorJvaGe/uNqI/vyFc2pMbooHGtt7GHeyhvaXwdpmxBo02PfMmMHGqtfzvP1WocrJb/+fzvkM7R2LtA==","shasum":"156409dd6399484fd1ebeb53763dfc88cf007dd5","tarball":"https://registry.npmjs.org/@ag9898/buddy/-/buddy-1.0.3.tgz","fileCount":23,"unpackedSize":3808734,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEQGS4iVxcYNxugwAd2FFi4z6dakbxHxMR2AHkh+ubSgAiEAh95I5yv2rpRfdWaB6ylMXBZugbjTmh3x1o46JKFbETU="}]},"_npmUser":{"name":"ag9898","email":"aden219898@gmail.com"},"directories":{},"maintainers":[{"name":"ag9898","email":"aden219898@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/buddy_1.0.3_1785858244325_0.724069109766023"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-17T22:12:36.932Z","modified":"2026-08-04T15:44:04.982Z","1.0.1":"2026-07-17T22:12:37.370Z","1.0.2":"2026-07-23T20:18:38.627Z","1.0.3":"2026-08-04T15:44:04.583Z"},"bugs":{"url":"https://github.com/AG9898/buddy/issues"},"author":{"name":"AG9898"},"license":"MIT","homepage":"https://github.com/AG9898/buddy#readme","keywords":["buddy","desktop-pet","electron","codex","claude-code","wsl"],"repository":{"type":"git","url":"git+https://github.com/AG9898/buddy.git"},"description":"Windows floating desktop pet for Codex CLI and Claude Code","maintainers":[{"name":"ag9898","email":"aden219898@gmail.com"}],"readme":"\n\n```\n ____ __ __\n / __ )__ ______/ /___/ /_ __\n / __ / / / / __ / __ / / / /\n / /_/ / /_/ / /_/ / /_/ / /_/ /\n/_____/\\__,_/\\__,_/\\__,_/\\__, /\n /____/\n```\n\n**A floating desktop pet for Windows that reacts to your AI coding assistant in real time.**\n\n[](https://www.npmjs.com/package/@ag9898/buddy)\n[](./LICENSE)\n[](https://www.npmjs.com/package/@ag9898/buddy)\n[](https://nodejs.org)\n\n
\n\n---\n\nbuddy renders a transparent, always-on-top pixel-art character directly on your Windows desktop. It listens to hook events from **Claude Code** and **Codex CLI** and animates the pet as your agent works — running when tools fire, jumping when you send a prompt, waiting for permissions, and waving when the session ends.\n\nNo login. No cloud. No installer GUI. Just `npm install -g @ag9898/buddy` and the `buddy` CLI.\nThe npm package includes the built app and installs the Electron runtime dependency that\n`buddy start` uses, so a global install does not need a source checkout.\n\n---\n\n## Contents\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [CLI Reference](#cli-reference)\n- [Pet States](#pet-states)\n- [Pet Management](#pet-management)\n- [Hook Integration](#hook-integration)\n- [Configuration](#configuration)\n- [Development](#development)\n- [Architecture](#architecture)\n- [Troubleshooting](#troubleshooting)\n\n---\n\n## Requirements\n\n| Requirement | Notes |\n|---|---|\n| **Windows 10 or 11** | The Electron overlay is Windows-only |\n| **Node.js 18+** | Required for `npm install -g @ag9898/buddy` |\n| **Claude Code** or **Codex CLI** | At least one required for hook integration |\n| **WSL** _(optional)_ | Only needed for WSL-side hook events via `petdex-bridge` |\n| **Codex CLI** _(optional)_ | Only needed for `buddy hatch` pet generation |\n\n---\n\n## Installation\n\n### Windows (PowerShell / Command Prompt)\n\n```sh\nnpm install -g @ag9898/buddy\nbuddy start\n```\n\nThe pet window appears on your desktop. `buddy start` launches the app detached and returns your prompt immediately.\n\n### WSL\n\n```sh\nnpm install -g @ag9898/buddy\nbuddy start # uses WSL interop to launch the Windows Electron app\nbuddy hooks install # wires Claude Code and Codex CLI hooks for WSL\n```\n\nWSL interop must be enabled. If `buddy.exe` is not reachable, buddy prints a clear actionable error.\n\n### WSL bridge\n\nInstall or build `petdex-bridge` inside WSL to route WSL shell hook events to the Windows pet:\n\n```sh\ncd petdex-bridge\ncargo build --release --target x86_64-unknown-linux-gnu\ntarget/x86_64-unknown-linux-gnu/release/petdex-bridge state running\n```\n\nThe bridge reads `BUDDY_PORT` (default `7777`) and sends authenticated JSON to\n`http://127.0.0.1:${BUDDY_PORT}/state`. It reads the update token from\n`$HOME/.petdex-win/runtime/update-token`; set `BUDDY_TOKEN` only as a temporary override.\nAfter starting buddy on Windows once, make WSL share that Windows-owned data directory:\n\n```sh\nln -s /mnt/c/Users//.petdex-win ~/.petdex-win\n```\n\nIf a symlink is not practical, copy the Windows `runtime/update-token` file into\n`$HOME/.petdex-win/runtime/update-token`, or set\n`BUDDY_DATA_DIR=/mnt/c/Users//.petdex-win` for WSL commands.\n\n---\n\n## Quick Start\n\n```sh\n# 1 — install\nnpm install -g @ag9898/buddy\n\n# 2 — launch the pet window\nbuddy start\n\n# 3 — wire up Claude Code + Codex CLI hooks\nbuddy hooks install\n\n# 4 — confirm everything is connected\nbuddy doctor\n```\n\nWithin seconds of your next `claude` or `codex` command the pet will start reacting.\n\n---\n\n## CLI Reference\n\n```\nbuddy [options]\n```\n\n| Command | Description |\n|---|---|\n| `buddy start` | Launch the Electron pet window, return control to the terminal. |\n| `buddy stop` | Quit the running pet app. |\n| `buddy update` | Explicitly update the globally installed package to the latest npm release. |\n| `buddy state ` | Manually push a state (`idle`, `running`, `waiting`, …). |\n| `buddy hooks install` | Write Claude Code + Codex CLI hook entries. |\n| `buddy hooks status` | Report hook coverage per assistant and event (read-only). |\n| `buddy hooks uninstall` | Remove only the hook entries buddy owns. |\n| `buddy doctor` | Health check: process, sidecar, token, and hook status. |\n| `buddy hatch ` | Generate a personal pet via Codex CLI image generation. |\n| `buddy pets list` | List all valid buddy-managed and Codex-compatible pets. |\n| `buddy pets current` | Print the currently active pet and its path (`buddy pets show` is an alias). |\n| `buddy pets use ` | Select and persist an active pet by ID. |\n\n### Options\n\n| Flag | Command | Description |\n|---|---|---|\n| `--id ` | `hatch` | Name the generated buddy-managed pet (otherwise derived from the prompt). |\n| `--output ` | `hatch` | Explicit custom output directory for the generated pet. |\n| `--package-preset ` | `hatch` | Maintainer-only: replace a bundled source-checkout preset. |\n| `--verbose` | `hatch` | Show raw Codex subprocess output. |\n| `--rc ` | `hooks install` | Deprecated compatibility flag; ignored. |\n\n---\n\n### Updating\n\nRun `buddy update` when you choose to update the globally npm-installed package:\n\n```sh\nbuddy update\n```\n\nbuddy never checks for or installs updates in the background. If npm reports a permission\nerror, rerun from an account that can update global npm packages.\n\n---\n\n## Pet States\n\nThe pet animates in response to your AI assistant's lifecycle events:\n\n```\nUserPromptSubmit → jumping\nPreToolUse → running\nPostToolUse → idle\nPermissionRequest → waiting\nStop → waving\n```\n\nTrigger a state manually at any time:\n\n```sh\nbuddy state running\nbuddy state idle\n```\n\n---\n\n## Pet Management\n\nbuddy discovers pets from three locations:\n\n| Source | Path | Notes |\n|---|---|---|\n| buddy-managed | `%USERPROFILE%\\.petdex-win\\pets` on Windows, `$HOME/.petdex-win/pets` in WSL | Created by `buddy hatch`. Override with `BUDDY_SPRITES_DIR`; use a WSL symlink/copy or `BUDDY_DATA_DIR` so WSL sees the Windows-owned directory. |\n| packaged | `<@ag9898/buddy package>\\pets` | Built-in read-only pets shipped with buddy: `default` and `penguin`. |\n| Codex-compatible | `%USERPROFILE%\\.codex\\pets` | Read-only asset folders — buddy never writes Codex state. |\n\nA valid pet folder contains a `pet.json` state machine and a `spritesheet.webp` (8 × 9 grid).\n\n### Included pets\n\nThe npm package ships with two ready-to-use pets:\n\n- `default` — the original bundled companion.\n- `penguin` — an animated penguin with idle, running, waiting, jumping, waving, failed, and review states.\n\nSelect either at any time:\n\n```sh\nbuddy pets use penguin\n```\n\n### Generating a pet\n\n`buddy hatch` delegates image generation to Codex CLI — buddy never holds image-provider credentials:\n\n```sh\nbuddy hatch \"a small orange cat\"\nbuddy hatch \"a small orange cat\" --id marmalade\nbuddy hatch \"a small orange cat\" --output C:\\\\art\\\\my-cat\nbuddy hatch \"a small orange cat\" --verbose\n```\n\nBy default, a hatch creates a personal pet in `%USERPROFILE%\\\\.petdex-win\\\\pets\\\\`,\nso it is available to `buddy pets` without changing the npm package. Use `--id` to choose\nthat folder name. `--package-preset ` is intentionally explicit and only for maintainers\nwho are replacing a bundled `pets/` asset in a source checkout. Codex CLI must be\ninstalled and signed in (`codex login`) before hatching. Use `BUDDY_CODEX_COMMAND` if Codex\nlives at a non-standard path.\n\n### Browsing and selecting pets\n\n```sh\nbuddy pets list # enumerate valid pets from all sources\nbuddy pets current # print the active selection (alias: buddy pets show)\nbuddy pets use orange-cat\n```\n\n---\n\n## Hook Integration\n\n`buddy hooks install` writes hook entries for Claude Code and Codex CLI in the current\nhost environment:\n\n- Claude Code: `~/.claude/settings.json`\n- Codex CLI: `~/.codex/hooks.json`\n- Windows hooks call `buddy state `\n- WSL hooks call `petdex-bridge state `\n\nAfter installing Codex hooks, open `/hooks` in Codex CLI if prompted and trust the new\nbuddy command hooks.\n\n`buddy hooks status` reports coverage per assistant and per event without changing\nanything. `buddy hooks uninstall` removes only the entries buddy wrote — unrelated hooks,\nevents, and settings in those files are preserved, repeated runs are no-ops, and a file\nbuddy cannot parse is reported instead of rewritten.\n\nThe event pipeline from there:\n\n```\n[ Claude Code / Codex CLI hook fires ]\n │\n ▼ (Windows) (WSL)\n buddy state petdex-bridge state \n │ │\n └──────────────┬───────────────────┘\n ▼\n POST 127.0.0.1:7777/state\n │\n ▼\n Electron HTTP sidecar\n (validates X-Petdex-Update-Token)\n │\n ▼\n Electron IPC → Svelte renderer\n │\n ▼\n pet animates ✓\n```\n\nAll traffic is loopback-only. No event data leaves your machine.\n\n---\n\n## Configuration\n\nAll variables are optional — buddy runs with safe built-in defaults, no `.env` required.\n\n| Variable | Default | Description |\n|---|---|---|\n| `BUDDY_PORT` | `7777` | Port for the local HTTP hook sidecar. |\n| `BUDDY_DATA_DIR` | `%USERPROFILE%\\.petdex-win` | Override the buddy-owned data root for state, token, and buddy-managed pets. In WSL, prefer symlinking `$HOME/.petdex-win` to the Windows directory. |\n| `BUDDY_TOKEN` | _(unset)_ | Temporary token override for `petdex-bridge`; normally read from `$HOME/.petdex-win/runtime/update-token`. |\n| `BUDDY_SPRITES_DIR` | `\\pets` | Override only the buddy-managed pets directory. |\n| `BUDDY_LOG_LEVEL` | `info` | Main process log level: `debug` `info` `warn` `error`. |\n| `BUDDY_CODEX_COMMAND` | `codex` | Codex CLI command used by `buddy hatch`. |\n| `BUDDY_VERBOSE` | _(unset)_ | Set to `1` to enable verbose output in `buddy hatch`. |\n\nTo override during development, create a `.env` at the project root:\n\n```sh\nBUDDY_PORT=7778\nBUDDY_LOG_LEVEL=debug\n```\n\n---\n\n## Development\n\n```sh\ngit clone \ncd buddy\nnpm install\n\nnpm run dev # Electron + Vite dev server with hot reload\nnpm test # Vitest unit tests\nnpm run lint # ESLint + svelte-check + tsc --noEmit\nnpm run build:app # build Electron bundles and out/cli/index.js\nnpm pack --dry-run # inspect the npm release tarball\nnpm run build:win:local # local smoke build, skips code signing\n```\n\n### Package contents\n\nThe public npm package is named `@ag9898/buddy`, but it installs the `buddy` command.\n`npm pack` runs `npm run build:app` through `prepack` and publishes only the built\nruntime output, bundled pets, icon/build metadata, README/LICENSE/CHANGELOG, and selected\nrelease docs. Agent skill folders, source-only planning files, tests, local caches,\nand workboard files are excluded by the package allowlist and `.npmignore` guardrail.\nElectron is installed as an optional production dependency of the package, which gives\n`buddy start` a runtime executable after `npm install -g @ag9898/buddy` without shipping\nsource-only dev dependencies.\n\n### WSL bridge (optional)\n\nRequires Rust with the `x86_64-unknown-linux-gnu` cross-compile target inside WSL:\n\n```sh\ncd petdex-bridge\ncargo build --release --target x86_64-unknown-linux-gnu\n```\n\n### Project layout\n\n```\nsrc/\n cli/ npm bin entry and subcommands\n main/ Electron main: window, sidecar, tray, state persistence\n preload/ contextBridge — petApi exposed to the Svelte renderer\n renderer/ Svelte pet renderer and sprite animation state machine\n shared/ IPC channel constants (imported by main / preload / tests)\npetdex-bridge/ Rust WSL bridge for shell hook events\npets/default/ Bundled default pet (pet.json + spritesheet.webp)\npets/penguin/ Bundled penguin pet (pet.json + spritesheet.webp)\ndocs/ Architecture, CLI contract, env vars, decisions, workboard\n```\n\n---\n\n## Architecture\n\nbuddy is four components talking locally — no network, no accounts, no cloud:\n\n```\n┌─────────────────────────────────────────────────────┐\n│ Windows desktop │\n│ │\n│ ┌─────────────┐ IPC ┌──────────────────┐ │\n│ │ buddy CLI │◄──────────►│ Electron main │ │\n│ │ (node bin) │ │ BrowserWindow │ │\n│ └─────────────┘ │ HTTP sidecar │ │\n│ │ System tray │ │\n│ └────────┬─────────┘ │\n│ │ IPC │\n│ ┌────────▼─────────┐ │\n│ │ Svelte renderer │ │\n│ │ sprite animate │ │\n│ └──────────────────┘ │\n└──────────────────────────────────▲──────────────────┘\n │ HTTP POST\n ┌──────┴──────┐\n │ WSL env │\n │ petdex- │\n │ bridge │\n │ (Rust CLI) │\n └─────────────┘\n```\n\n| Component | Responsibility |\n|---|---|\n| **buddy CLI** | Detects Windows vs WSL, launches/stops the app, installs hooks, sends state. |\n| **Electron main** | Transparent always-on-top `BrowserWindow`, HTTP sidecar, state persistence, tray. |\n| **Svelte renderer** | CSS sprite animation, drag and resize interactions via `contextBridge`. |\n| **petdex-bridge** | WSL Rust binary — called by shell hooks, POSTs to sidecar via localhost passthrough. |\n\nFull details: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)\n\n---\n\n## Troubleshooting\n\n**Pet window doesn't appear**\n```sh\nbuddy doctor # checks process, sidecar, token, and hook status in one pass\n```\n`buddy doctor` also verifies that the Electron runtime dependency is present. If that\ncheck fails, reinstall with `npm install -g @ag9898/buddy`.\n\n**Hooks aren't triggering animations**\nRe-run `buddy hooks install`, restart your shell, and confirm your AI CLI fires hooks.\n\n**`buddy start` from WSL fails (interop error)**\nWSL interop must be enabled. Verify `cmd.exe` is reachable from within your WSL session.\n\n**`buddy hatch` fails immediately**\n```sh\ncodex doctor # verify Codex CLI is installed and authenticated\n```\nSet `BUDDY_CODEX_COMMAND` if Codex is at a non-standard path.\n\n**Pet is off-screen after a monitor change**\n```sh\nbuddy stop && buddy start # startup clamps bounds into the current display work area\n```\n\n---\n\n\n\nMIT License · Windows only · No telemetry · No accounts · Local-only\n\n
\n","readmeFilename":"README.md"}