+ 
+
+
+## 📖 About
+
+**Cursor Agent** turns every prompt into real work — but what if that effort also fed a partner
+that grows with you? **Cursor VPet** adds a Digimon virtual pet to the Explorer sidebar. Your
+partner gains experience from Agent token usage and evolves through classic Digimon stages.
+
+It shares the same `pet.db` database as
+[@sbugallo/opencode-vpet](https://www.npmjs.com/package/@sbugallo/opencode-vpet), so progress
+carries over between Cursor and OpenCode.
+
+
+ Cursor VPet
++ Digimon virtual pet for Cursor that evolves as you use Agent — shares progress with OpenCode VPet +
+ +[](https://open-vsx.org/extension/sbugallo/cursor-vpet) +[](https://open-vsx.org/extension/sbugallo/cursor-vpet) +[](https://open-vsx.org/extension/sbugallo/cursor-vpet) +[](LICENSE) + +[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • +[Commands](#-commands) • [Settings](#%EF%B8%8F-settings) • [Storage](#-storage) • +[How It Works](#-how-it-works) • [Authors](#-authors) + +[](https://open-vsx.org/extension/sbugallo/cursor-vpet) + +[](https://github.com/sbugallo/opencode-vpet/releases) + +--- + +
+
+
+
+### 🎯 Key Highlights
+
+- 🐣 **Evolves with Agent usage** — Input, output, and cache tokens from Agent turns count
+- 🔄 **Shared with OpenCode** — Same `pet.db`, Dex, and generation history across tools
+- 🎮 **650 Digimon** — Evolution lines extracted from the original V-Pets
+- 📊 **Sidebar + panels** — Live partner view, Dex browser, and generation history
+- 🪝 **Reliable tracking** — Cursor hooks with API watermark fallback
+- 🔒 **Privacy-first** — Local SQLite storage, no telemetry
+- ⏸️ **Freeze anytime** — Pause progression without losing your partner
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+| --- | --- |
+| **Sidebar webview** | Animated ASCII partner artwork with stage gauge and evolution progress |
+| **Dex panel** | Browse discovered Digimon from your collection |
+| **History panel** | Review current and retired partner generations |
+| **Token tracking** | Cursor hooks (`beforeSubmitPrompt` + `stop`) with API watermark fallback |
+| **Shared database** | Compatible `pet.db` with the OpenCode VPet plugin |
+| **Partner commands** | Spawn, freeze, unfreeze, and set Digimon by catalog ID |
+| **Hook management** | Install or uninstall hooks from the Command Palette |
+
+---
+
+## 📦 Installation
+
+### Open VSX (Cursor / VSCodium)
+
+Open Quick Open (`Ctrl+P` / `Cmd+P`) and run:
+
+```
+ext install sbugallo.cursor-vpet
+```
+
+Or search for **Cursor VPet** in the Extensions sidebar, or install from
+[Open VSX](https://open-vsx.org/extension/sbugallo/cursor-vpet).
+
+### VSIX (manual)
+
+Download the `.vsix` from
+[GitHub Releases](https://github.com/sbugallo/opencode-vpet/releases) and run
+**Extensions → Install from VSIX…**.
+
+---
+
+## 🚀 Usage
+
+### First run — install hooks
+
+On first activation, the extension prompts you to register hooks in `~/.cursor/hooks.json`.
+Hooks are required for reliable Agent token tracking.
+
+You can also run **Cursor VPet: Install Hooks** from the Command Palette at any time.
+
+### Sidebar
+
+Open the **VPet** view in the Explorer sidebar to see your active partner, evolution gauge,
+and animated artwork.
+
+### Hatch a partner
+
+1. Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
+2. Run **Cursor VPet: Spawn Partner**
+
+Your partner starts as an egg and evolves as you complete Agent turns.
+
+### Other access methods
+
+- **Command Palette** — all `Cursor VPet:` commands
+- **Explorer sidebar** — **VPet** webview panel
+
+---
+
+## 🎮 Commands
+
+| Command | Description |
+| --- | --- |
+| **Cursor VPet: Spawn Partner** | Hatches a new egg |
+| **Cursor VPet: Freeze** | Pauses partner progression |
+| **Cursor VPet: Unfreeze** | Resumes partner progression |
+| **Cursor VPet: Set Digimon** | Overrides the partner with a catalog ID (e.g. `3-001`) |
+| **Cursor VPet: Open Dex** | Opens the partner Dex panel |
+| **Cursor VPet: Open History** | Opens the generation history panel |
+| **Cursor VPet: Install Hooks** | Registers hooks in `~/.cursor/hooks.json` |
+| **Cursor VPet: Uninstall Hooks** | Removes VPet hooks from `~/.cursor/hooks.json` |
+
+> **Note:** Using **Set Digimon** does not count toward Dex completion.
+
+---
+
+## 📝 Examples
+
+### Shared database with OpenCode
+
+By default, both Cursor VPet and OpenCode VPet use the same `pet.db` location. To share a
+custom file, set the same path in both tools:
+
+
+```json
+{
+ "vpet.databasePath": "/path/to/shared/pet.db"
+}
+```
+
+### Slower API watermark fallback
+
+If token deltas are not captured immediately after Agent turns, increase the settle delay:
+
+```json
+{
+ "vpet.usage.settleDelayMs": 8000
+}
+```
+
+---
+
+## ⚙️ Settings
+
+Configure via **File → Preferences → Settings** and search for `vpet`.
+
+| Setting | Default | Description |
+| --- | --- | --- |
+| `databasePath` | _(empty)_ | Override path to `pet.db` (default: shared opencode-vpet location) |
+| `usage.settleDelayMs` | `4000` | Initial delay before API watermark fallback (ms) |
+
+> Changing `databasePath` requires reloading the Cursor window.
+
+Stage labels and evolution thresholds use the built-in defaults from `@sbugallo/vpet-core`
+(Japanese naming by default). The OpenCode plugin can override these via
+[`opencode-vpet.json`](https://github.com/sbugallo/opencode-vpet#settings); Cursor VPet does
+not read that file yet.
+
+---
+
+## 🔧 Requirements
+
+| Requirement | Details |
+| --- | --- |
+| **Cursor** | Token tracking requires Cursor (`state.vscdb` must be present) |
+| **Node.js** | Required to run `hook-bridge.js` from Cursor hooks |
+| **Hooks** | `beforeSubmitPrompt` and `stop` entries in `~/.cursor/hooks.json` |
+
+The extension shows a warning if it cannot detect the Cursor runtime. VS Code alone is not
+enough for token tracking, though the sidebar and panels still work with an existing `pet.db`.
+
+---
+
+## 💾 Storage
+
+Partner state, Dex discoveries, and generation history are stored in a SQLite database named
+`pet.db`. By default it uses the same location as OpenCode VPet:
+
+| Platform | Default path |
+| --- | --- |
+| **macOS** | `~/Library/Application Support/opencode-vpet/pet.db` |
+| **Linux / WSL** | `~/.local/share/opencode-vpet/pet.db` |
+| **Windows** | `%APPDATA%\opencode-vpet\pet.db` |
+
+Override with `vpet.databasePath` to use a custom file.
+
+---
+
+## 🏗️ How It Works
+
+```
+┌──────────────┐ ┌───────────────┐ ┌────────────────────┐ ┌─────────┐
+│ Cursor hooks │ ──▶ │ hook-bridge.js│ ──▶ │ vpet-hook-events │ ──▶ │ pet.db │
+│ before/stop │ │ (Node) │ │ .jsonl │ │ SQLite │
+└──────────────┘ └───────────────┘ └────────────────────┘ └─────────┘
+ │
+ ▼
+ ┌─────────────────┐
+ │ Sidebar webview │
+ │ Dex · History │
+ └─────────────────┘
+```
+
+1. Cursor hooks fire on `beforeSubmitPrompt` and `stop` for each Agent turn
+2. `hook-bridge.js` appends structured events to `~/.cursor/vpet-hook-events.jsonl`
+3. The extension watches the event log and maps stop payloads to completed usage
+4. If stop tokens are missing, it falls back to Cursor's usage API (watermark delta)
+5. Usage is applied through `@sbugallo/vpet-core` evolution logic into `pet.db`
+6. The sidebar webview refreshes with updated partner state and artwork
+
+---
+
+## 🔒 Privacy
+
+- ✅ No extension telemetry or analytics
+- ✅ Partner data stays in your local `pet.db`
+- ✅ Hook events are written only to `~/.cursor/vpet-hook-events.jsonl`
+- ⚠️ API watermark fallback reads your Cursor access token from local `state.vscdb` and
+ queries `cursor.com/api/dashboard/get-filtered-usage-events` to compute token deltas
+- ⚠️ When stop hooks include token counts, no network request is needed for that turn
+
+---
+
+## 🐛 Known Issues
+
+| Issue | Workaround |
+| --- | --- |
+| Tokens not recorded after Agent turns | Run **Cursor VPet: Install Hooks** and retry |
+| Missing token data in stop hook | Increase `vpet.usage.settleDelayMs` (e.g. `8000`) |
+| Running in VS Code instead of Cursor | Token tracking is unavailable; use Cursor for Agent usage |
+| Database path change not applied | Reload the Cursor window after changing settings |
+
+---
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome in the monorepo!
+
+1. Fork the [repository](https://github.com/sbugallo/opencode-vpet)
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+Package path: [`packages/cursor-vpet`](https://github.com/sbugallo/opencode-vpet/tree/main/packages/cursor-vpet)
+
+---
+
+## 👤 Authors
+
+| Role | Name |
+| --- | --- |
+| **Author** | [Sergio Bugallo](https://github.com/sbugallo) |
+| **Collaborator** | [Jorge Cendal](https://github.com/jcendal) |
+
+---
+
+## 📜 License
+
+[Apache-2.0](LICENSE)
+
+Part of the [opencode-vpet](https://github.com/sbugallo/opencode-vpet) monorepo. Digimon
+sprites were derived from community sources — see the
+[root README attributions](https://github.com/sbugallo/opencode-vpet#attributions).
+
+---
+
+
+
+
+**Built with ❤️ for the developer community**
+
+[⬆ Back to Top](#cursor-vpet)
+
+
diff --git a/packages/cursor-vpet/hook-bridge.js b/packages/cursor-vpet/hook-bridge.js
new file mode 100644
index 0000000..9c0119a
--- /dev/null
+++ b/packages/cursor-vpet/hook-bridge.js
@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Cursor hook bridge — reads hook JSON from stdin, appends to events file, responds {}.
+ * Fail-open: never blocks Cursor on errors.
+ */
+import { appendFileSync, mkdirSync } from "node:fs"
+import { homedir } from "node:os"
+import { dirname, join } from "node:path"
+import { Readable } from "node:stream"
+
+const EVENTS_PATH =
+ process.env.VPET_HOOK_EVENTS_PATH ?? join(homedir(), ".cursor", "vpet-hook-events.jsonl")
+
+const readStdin = async () => {
+ const chunks = []
+ for await (const chunk of Readable.toWeb(process.stdin)) {
+ chunks.push(Buffer.from(chunk))
+ }
+ return Buffer.concat(chunks).toString("utf8")
+}
+
+const main = async () => {
+ const raw = await readStdin()
+ if (raw.trim().length === 0) {
+ process.stdout.write("{}")
+ return
+ }
+
+ let payload
+ try {
+ payload = JSON.parse(raw)
+ } catch {
+ process.stdout.write("{}")
+ return
+ }
+
+ const hookEventName =
+ typeof payload.hook_event_name === "string" ? payload.hook_event_name : process.argv[2] ?? "unknown"
+
+ const record = {
+ receivedAt: new Date().toISOString(),
+ hookEventName,
+ payload,
+ }
+
+ try {
+ mkdirSync(dirname(EVENTS_PATH), { recursive: true })
+ appendFileSync(EVENTS_PATH, `${JSON.stringify(record)}\n`, "utf8")
+ } catch (error) {
+ console.error("[vpet-hook-bridge]", error)
+ }
+
+ process.stdout.write("{}")
+}
+
+main().catch((error) => {
+ console.error("[vpet-hook-bridge]", error)
+ process.stdout.write("{}")
+})
diff --git a/packages/cursor-vpet/icon.png b/packages/cursor-vpet/icon.png
new file mode 100644
index 0000000..bd1aab4
Binary files /dev/null and b/packages/cursor-vpet/icon.png differ
diff --git a/packages/cursor-vpet/package.json b/packages/cursor-vpet/package.json
new file mode 100644
index 0000000..a12ed1f
--- /dev/null
+++ b/packages/cursor-vpet/package.json
@@ -0,0 +1,124 @@
+{
+ "name": "cursor-vpet",
+ "displayName": "Cursor VPet",
+ "description": "Digimon virtual pet for Cursor that evolves with Agent token usage.",
+ "version": "0.2.0-dev.0",
+ "publisher": "sbugallo",
+ "license": "Apache-2.0",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/sbugallo/opencode-vpet.git",
+ "directory": "packages/cursor-vpet"
+ },
+ "homepage": "https://github.com/sbugallo/opencode-vpet#readme",
+ "bugs": {
+ "url": "https://github.com/sbugallo/opencode-vpet/issues"
+ },
+ "keywords": [
+ "cursor",
+ "vpet",
+ "virtual-pet",
+ "digimon",
+ "agent",
+ "ai",
+ "sidebar",
+ "opencode"
+ ],
+ "icon": "icon.png",
+ "galleryBanner": {
+ "color": "#1a1a2e",
+ "theme": "dark"
+ },
+ "engines": {
+ "vscode": "^1.90.0",
+ "node": "24.11.0",
+ "bun": "1.3.5"
+ },
+ "categories": [
+ "Other"
+ ],
+ "activationEvents": [
+ "onStartupFinished"
+ ],
+ "main": "./dist/extension.js",
+ "contributes": {
+ "views": {
+ "explorer": [
+ {
+ "id": "cursorVpet.sidebar",
+ "name": "VPet",
+ "type": "webview"
+ }
+ ]
+ },
+ "commands": [
+ {
+ "command": "cursorVpet.spawn",
+ "title": "Cursor VPet: Spawn Partner"
+ },
+ {
+ "command": "cursorVpet.freeze",
+ "title": "Cursor VPet: Freeze"
+ },
+ {
+ "command": "cursorVpet.unfreeze",
+ "title": "Cursor VPet: Unfreeze"
+ },
+ {
+ "command": "cursorVpet.set",
+ "title": "Cursor VPet: Set Digimon"
+ },
+ {
+ "command": "cursorVpet.dex",
+ "title": "Cursor VPet: Open Dex"
+ },
+ {
+ "command": "cursorVpet.history",
+ "title": "Cursor VPet: Open History"
+ },
+ {
+ "command": "cursorVpet.installHooks",
+ "title": "Cursor VPet: Install Hooks"
+ },
+ {
+ "command": "cursorVpet.uninstallHooks",
+ "title": "Cursor VPet: Uninstall Hooks"
+ }
+ ],
+ "configuration": {
+ "title": "Cursor VPet",
+ "properties": {
+ "vpet.databasePath": {
+ "type": "string",
+ "default": "",
+ "description": "Override path to pet.db (default: shared opencode-vpet/pet.db)"
+ },
+ "vpet.usage.settleDelayMs": {
+ "type": "number",
+ "default": 4000,
+ "description": "Initial delay before API watermark fallback (ms)"
+ }
+ }
+ }
+ },
+ "scripts": {
+ "build": "bun scripts/build.ts",
+ "check": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.scripts.json",
+ "test": "bun test",
+ "package": "npx @vscode/vsce package --no-dependencies",
+ "publish:openvsx": "npx ovsx publish *.vsix -p \"$OVSX_PAT\"",
+ "vscode:prepublish": "bun run build"
+ },
+ "dependencies": {
+ "@sbugallo/vpet-core": "workspace:*",
+ "sql.js": "^1.12.0"
+ },
+ "devDependencies": {
+ "@types/bun": "1.3.14",
+ "@types/node": "24.10.1",
+ "@types/vscode": "1.90.0",
+ "@vscode/vsce": "3.2.1",
+ "ovsx": "0.10.0",
+ "typescript": "5.9.3"
+ }
+}
diff --git a/packages/cursor-vpet/scripts/build.ts b/packages/cursor-vpet/scripts/build.ts
new file mode 100644
index 0000000..126beee
--- /dev/null
+++ b/packages/cursor-vpet/scripts/build.ts
@@ -0,0 +1,30 @@
+import { copyFile, mkdir, rm } from "node:fs/promises"
+import { createRequire } from "node:module"
+import { resolve } from "node:path"
+
+import { stageChangelog } from "./stage-changelog.ts"
+
+const require = createRequire(import.meta.url)
+const packageRoot = resolve(import.meta.dir, "..")
+const distDirectory = resolve(packageRoot, "dist")
+const wasmSource = require.resolve("sql.js/dist/sql-wasm.wasm")
+
+await rm(distDirectory, { recursive: true, force: true })
+await mkdir(distDirectory, { recursive: true })
+await stageChangelog(packageRoot)
+
+const result = await Bun.build({
+ entrypoints: ["./src/extension.ts"],
+ outdir: "./dist",
+ target: "node",
+ format: "cjs",
+ external: ["vscode"],
+ minify: true,
+ sourcemap: false,
+})
+
+if (!result.success) {
+ throw new Error("cursor-vpet build failed")
+}
+
+await copyFile(wasmSource, resolve(distDirectory, "sql-wasm.wasm"))
diff --git a/packages/cursor-vpet/scripts/stage-changelog.ts b/packages/cursor-vpet/scripts/stage-changelog.ts
new file mode 100644
index 0000000..a3d37ea
--- /dev/null
+++ b/packages/cursor-vpet/scripts/stage-changelog.ts
@@ -0,0 +1,33 @@
+import { copyFile, rm } from "node:fs/promises"
+import { resolve } from "node:path"
+
+export const getMonorepoChangelogPath = (packageRoot: string): string => resolve(packageRoot, "../../CHANGELOG.md")
+
+export const getStagedChangelogPath = (packageRoot: string): string => resolve(packageRoot, "CHANGELOG.md")
+
+export const stageChangelog = async (packageRoot: string): PromiseVPet Dex
+Discovered: ${discoveredCount} / ${model.rows.length}
+| Name | Stage | Found |
|---|
VPet History
+| Gen | Path | Created |
|---|
Loading VPet…
+
+
+`
diff --git a/packages/cursor-vpet/src/webview/vpet-sidebar-provider.ts b/packages/cursor-vpet/src/webview/vpet-sidebar-provider.ts
new file mode 100644
index 0000000..4725b55
--- /dev/null
+++ b/packages/cursor-vpet/src/webview/vpet-sidebar-provider.ts
@@ -0,0 +1,238 @@
+import * as vscode from "vscode"
+
+import type { UsageEvolutionTransition } from "@sbugallo/vpet-core/application/models/usage.ts"
+import { DEFAULT_VPET_SETTINGS } from "@sbugallo/vpet-core/config/defaults.ts"
+import { DIGIMON_CATALOG } from "@sbugallo/vpet-core/data/catalog.ts"
+import { MONSTER_FRAME_CATALOG } from "@sbugallo/vpet-core/data/monster-frame-catalog.ts"
+import { getSidebarCardInputs } from "@sbugallo/vpet-core/application/use-cases/get-sidebar-card-inputs.ts"
+import type { SidebarSnapshotReader } from "@sbugallo/vpet-core/application/ports/sidebar-snapshot.ts"
+import type { EvolutionBattleRepository } from "@sbugallo/vpet-core/application/use-cases/resolve-evolution-battle.ts"
+import { buildSidebarCardModel } from "@sbugallo/vpet-core/view-models/sidebar-view-model.ts"
+import { renderPositionedArtwork } from "./animated-artwork.ts"
+import { runEvolutionBattleSession } from "./evolution-battle-session.ts"
+import { runEvolutionRevealSession } from "./evolution-reveal-session.ts"
+import { MonsterAnimationController, type MonsterAnimationOutput } from "./monster-animation.ts"
+import {
+ buildSidebarWebviewHtml,
+ DEFAULT_ARTWORK_WIDTH,
+ MIN_ARTWORK_WIDTH,
+ toSidebarWebviewPayload,
+ type SidebarWebviewPayload,
+} from "./sidebar-render.ts"
+
+const VISUAL_INTERVAL_MS = 500
+
+export class VpetSidebarProvider implements vscode.WebviewViewProvider {
+ public static readonly viewType = "cursorVpet.sidebar"
+
+ private view?: vscode.WebviewView
+ private cachedPayload?: SidebarWebviewPayload
+ private cachedArtwork = ""
+ private artworkWidth = DEFAULT_ARTWORK_WIDTH
+ private visualInterval?: ReturnType
+ 
+
+
+---
+
+## About
+
+
+ opencode-vpet
++ A Digimon virtual pet for OpenCode that evolves with usage. +
++ About | + Evolution | + Quick start | + Commands | + Settings | + Storage | + Partner list | + License | + Attributions + +
+
+ 
+
+
+`@sbugallo/opencode-vpet` is an OpenCode v1 plugin that adds a Digimon virtual pet to your OpenCode TUI
+sidebar. Your Digimon evolves as you use OpenCode, and you can browse your discoveries and
+partner history.
+
+The plugin support multiple concurrent sessions, so every token counts to evolve your partner.
+
+There are more than 600 Digimon to discover, and the plugin is designed to be extensible so that new Digimon can be added in future releases.
+
+## Evolution
+
+Your active partner gains experience from the tokens reported for completed assistant
+messages in OpenCode. This includes input, output, reasoning, and cache tokens.
+Progress is shared across concurrent OpenCode sessions, so completed work in each
+session contributes to the same partner.
+
+Each stage has a configurable experience threshold. When your partner reaches the
+threshold for its current stage, it evolves and its experience gauge resets for the
+next stage. Use `/vpet-freeze` to pause partner progression; usage while frozen is
+not applied to your partner.
+
+The bundled evolution lines were extracted from the original V-Pets. When a Digimon
+reaches an evolution threshold, the plugin randomly chooses one of the evolution
+options in that Digimon's line.
+
+## Quick start
+
+Requirements:
+- OpenCode `>=1.18.10`
+- Node `>=20` to run `npx`
+- Bun `>=1.3.5` only for local development
+
+
+1. Install both plugins:
+
+ ```sh
+ npx @sbugallo/opencode-vpet init
+ ```
+
+ The CLI delegates to `opencode plugin @sbugallo/opencode-vpet@
+