opencode-buddy 0.2.1 → 0.3.0

package/README.md

@@ -1,204 +1,125 @@
 # opencode-buddy
 
-A virtual ASCII pet companion for [opencode](https://opencode.ai). Use it as a `/buddy` slash command inside opencode, or as a tmux side pane next to it.
-
-```
-    opencode TUI                                   buddy pane
-    ┌──────────────────────┐         ┌──────────────────────┐
-    │                      │         │ ╭─ Quack the duck ─╮  │
-    │   your opencode      │         │       __            │ │
-    │   TUI here           │         │     <(o )___        │ │
-    │                      │         │      ( ._> /        │ │
-    │                      │         │       `--'          │ │
-    │                      │         │                      │ │
-    │                      │         │ hunger ████████░░ 79 │ │
-    │                      │         │ happy  ████████░░ 79 │ │
-    │                      │         │ energy ██████████ 100 │ │
-    │                      │         │ keys: f feed · ...   │ │
-    └──────────────────────┘         └──────────────────────┘
-```
-
-The buddy reacts to what you're doing — idles when you idle, cheers when opencode finishes a turn, gets scared when a session errors, falls asleep when energy runs low.
-
-## Why?
-
-Claude Code v2.1.88 had a fun `/buddy` easter egg (an ASCII pet companion). When Anthropic removed it in v2.1.97 the community revolted. This is the opencode equivalent: your own buddy, open source, never going to be taken away.
+A virtual ASCII pet companion that lives in the opencode TUI sidebar. Hatches, feeds, plays, and reacts to what you're coding — all without leaving opencode.
+
+```
+┌──────────────────────────┐
+│  opencode TUI            │
+│                          │
+│  > your prompt here      │
+│                          │
+│         sidebar          │
+│ ┌──────────────────────┐ │
+│ │ Quack the duck       │ │
+│ │       __             │ │
+│ │     <(o )___         │ │
+│ │      ( ._> /         │ │
+│ │       `--'           │ │
+│ │ ──────────────────── │ │
+│ │ hunger ████████░░ 79 │ │
+│ │ happy  ████████░░ 79 │ │
+│ │ energy ██████████ 100│ │
+│ │ idle · Lv 1 · xp 0   │ │
+│ └──────────────────────┘ │
+└──────────────────────────┘
+```
+
+The buddy blinks every 600ms. Switch species, watch it cheer when opencode finishes a turn, and get scared when a session errors.
 
 ## Install
 
-Requires Node.js ≥ 18. tmux is only needed for the side-pane mode (Mode B).
-
-### Mode A: `/buddy` inside opencode (recommended)
+Requires Node.js ≥ 18 and opencode ≥ 1.15.
 
 ```bash
 npm install -g opencode-buddy
-opencode-buddy install
 ```
 
-This writes `~/.config/opencode/commands/buddy.md` and adds
-`opencode-buddy` to your `opencode.json` `plugin` list. **Restart
-opencode.** Then in the TUI:
+Add to your `~/.config/opencode/opencode.json`:
 
-```
-/buddy                  show current status
-/buddy feed             feed the buddy
-/buddy play             play with the buddy (+xp)
-/buddy rest             tuck the buddy in
-/buddy switch cat       become a cat
-/buddy switch dragon    become a dragon
-/buddy rename Mia       rename
-/buddy hatch dragon Sparky  start fresh
-/buddy ascii            render ASCII art inline
-/buddy help             list all actions
+```json
+{
+  "plugin": ["opencode-buddy"]
+}
 ```
 
-The buddy's mood is updated automatically: `session.idle` makes it
-celebrate, `session.error` makes it scared, low energy sends it to sleep.
+Restart opencode. The buddy appears in the sidebar.
 
-### Mode B: tmux side pane (optional, for a permanent companion)
+## How to interact
 
-```bash
-npm install -g opencode-buddy
-```
+The buddy has a `buddy` tool the LLM can call. Just talk to it:
 
-In any tmux pane (next to your opencode pane):
-
-```bash
-opencode-buddy start
 ```
-
-A 28-column side pane splits off to the right and the buddy appears
-inside it, rendered in full ASCII with color. Press keys in the buddy
-pane to interact:
-
-| Key | Action |
-| --- | --- |
-| `f` | Feed (+25 hunger) |
-| `p` | Play (+20 happiness, +5 xp) |
-| `z` | Rest (+30 energy) |
-| `r` | Rename (prompts in the pane) |
-| `s` | Switch species (cycles through 6) |
-| `n` | Hatch a new buddy (resets state) |
-| `q` | Quit (kills the side pane) |
-
-**Modes A and B share the same persisted state** at
-`~/.config/opencode-buddy/state.json`, so feeding the buddy via
-`/buddy feed` in the TUI will also be reflected in the side pane and
-vice versa.
-
-### Install from source
-
-```bash
-git clone https://github.com/AMark-CS/opencode-buddy
-cd opencode-buddy
-npm install            # only for plugin dev deps
-npm link               # adds `opencode-buddy` to PATH
-opencode-buddy install
+/buddy
+/feed the buddy
+/switch to a dragon
+/rename it to Sparky
+/can you show me the buddy's ascii art
 ```
 
-### Uninstall
+The LLM will call the `buddy` tool with the right action. Available actions:
 
-```bash
-opencode-buddy uninstall
-npm uninstall -g opencode-buddy
-```
-
-## Headless commands
-
-```bash
-opencode-buddy stats                      # one-line status printout
-opencode-buddy feed                       # feed from any terminal
-opencode-buddy hatch dragon Sparky        # start fresh as a dragon named Sparky
-opencode-buddy switch cat                 # become a cat
-opencode-buddy rename CaptainQuack        # rename
-opencode-buddy notify done                # nudge the buddy from a hook
-opencode-buddy path                       # print path to the state file
-```
-
-These work whether or not the TUI or tmux side pane is running.
-| `n` | Hatch a new buddy (resets state) |
-| `q` | Quit (kills the side pane) |
-
-### Headless commands
-
-```bash
-opencode-buddy stats                      # one-line status printout
-opencode-buddy feed                       # feed from any terminal
-opencode-buddy hatch dragon Sparky        # start fresh as a dragon named Sparky
-opencode-buddy switch cat                 # become a cat
-opencode-buddy rename CaptainQuack        # rename
-opencode-buddy notify done                # nudge the buddy from a hook / hookup
-opencode-buddy path                       # print path to the state file
-```
+| Action | Effect |
+| --- | --- |
+| `status` | Print current stats |
+| `feed` | +25 hunger, -5 energy |
+| `play` | +20 happiness, -5 hunger, +5 xp |
+| `rest` | +30 energy |
+| `switch <species>` | Change to duck, cat, dragon, axolotl, robot, or ghost |
+| `rename <name>` | Rename (max 20 chars) |
+| `hatch [species] [name]` | Start a brand new buddy |
+| `ascii [frame]` | Return rendered ASCII art |
+| `path` | Path to the state file |
+| `help` | List actions |
 
-## The six species
+## Six species
 
 ```
        duck                    cat                  dragon
-         __                /\\_/\                  /\\_/\
+         __                /\_/\                  /\_/\
        <(o )___          ( o.o )                ( o o )  ~~
         ( ._> /           > ^ <                  > ^ < /
-         `--'            /|   |\\               /|   |\\
-      ~ idle ~         (_|   |_)              (_|   |_)
+         `--'            /|   |\                /|   |\
+      ~ idle ~         (_|   |_)               (_|   |_)
                           meow                   rawr
 
      axolotl                robot                  ghost
       ^___^              [ O . O ]              .-"\"-.
-     (o . o)             /|#####|\\             ( o . o )
-    \\|_|_|/            / |#####| \\            | ~  ~ |
-     \\| |/              |     |                |     |
-      ) (               /| | | |\\              \\uuuuu/
+     (o . o)             /|#####|\              ( o . o )
+    \|_|_|/             / |#####| \             | ~  ~ |
+     \| |/               |     |                |     |
+      ) (               /| | | |\               \uuuuu/
     ~ ambien              beep                   boo
 ```
 
-Each has frames for `idle / working / celebrating / scared / sleeping`.
+Each species has a per-character color palette. Idle state has 3 frames (blink loop) at 600ms per frame.
 
 ## How it works
 
-* **As an opencode plugin** (`src/plugin.js`): registers a `buddy` tool the LLM can call, and listens to `session.idle` / `session.error` events to update the buddy's mood automatically. The `/buddy` slash command in `~/.config/opencode/commands/buddy.md` is a thin prompt that tells the LLM to use that tool.
-* **As a tmux sidecar** (`bin/opencode-buddy.js start`): runs a separate process in a right-side tmux pane. Uses `tmux capture-pane` to peek at the opencode pane text and infer whether opencode is generating, errored, or idle.
-* **Shared state** at `~/.config/opencode-buddy/state.json`. Both the plugin and the sidecar read and write the same file, so a `/buddy feed` in the TUI is immediately visible in the side pane and vice versa.
-* **Zero runtime dependencies.** Pure Node.js + ANSI escapes for the renderer, `spawnSync("tmux", ...)` for pane control. The only dev-time dependency is `@opencode-ai/plugin` (used to define the opencode tool).
+- **TUI plugin** (`src/tui-plugin.jsx`): registers `sidebar_content` slot, renders a Solid component that polls `~/.config/opencode-buddy/state.json` every 1.5s and animates at 6fps. Pure opencode-native — no tmux, no separate process.
+- **Server plugin** (`src/server-plugin.js`): registers a `buddy` tool the LLM can call. The same package exports both entrypoints (`main` for server, `exports["./tui"]` for TUI).
+- **State** at `~/.config/opencode-buddy/state.json` (~/.config is cross-platform via os.homedir()). Attributes decay over time. Sessions auto-celebrate on `session.idle` and auto-scare on `session.error`.
+
+## Uninstall
 
-## Limitations
+```bash
+npm uninstall -g opencode-buddy
+```
 
-* **Activity inference is best-effort.** If opencode's prompt text changes, the heuristics may misclassify. The `notify` subcommand is the explicit way to push events.
-* **The /buddy command is LLM-mediated.** The slash command is a prompt that tells opencode's LLM to call the `buddy` tool. It works only inside an active opencode session. For a direct terminal-friendly interface use `opencode-buddy <subcommand>` or the tmux side pane.
-* **No animations yet.** Frames are static; the renderer just swaps the frame when the state changes. Adding 2-3 frame loops per state is straightforward (PRs welcome).
+Then remove `"opencode-buddy"` from your `opencode.json` `plugin` array.
 
 ## Project layout
 
 ```
 opencode-buddy/
-├── bin/
-│   └── opencode-buddy.js     # CLI entry
-├── src/
-│   ├── plugin.js             # opencode plugin (exports BuddyPlugin)
-│   ├── install.js            # one-shot installer for /buddy + opencode.json
-│   ├── index.js              # CLI runtime + headless commands
-│   ├── tui.js                # ANSI renderer for the side pane
-│   ├── tmux.js               # tmux capture / split helpers
-│   ├── persistence.js        # state file at ~/.config/opencode-buddy/
-│   └── buddy/
-│       ├── species.js        # ASCII art + color palettes
-│       └── state.js          # state machine + attribute math
-├── test/
-│   ├── smoke.js              # state / species unit tests
-│   ├── plugin.smoke.js       # plugin tool unit tests
-│   └── e2e.js                # full tmux roundtrip
 ├── package.json
-├── LICENSE                   # MIT
 ├── README.md
-├── PUSH.md                   # GitHub push guide
-└── PUBLISH.md                # npm publish guide
-```
-
-## Development
-
-```bash
-npm test              # runs all unit tests (smoke + plugin)
-npm run test:e2e      # runs end-to-end tmux test (creates & kills a session)
-npm run install-buddy # runs the opencode install command
+├── LICENSE
+└── src/
+    ├── tui-plugin.jsx     # v2 TUI plugin, mounts to sidebar_content
+    ├── server-plugin.js   # v1 server plugin, exposes `buddy` tool
+    ├── species.js         # ASCII art + per-species color palettes
+    ├── state.js           # state machine (hunger/happiness/energy decay)
+    └── persistence.js     # state file reader/writer
 ```
 
 ## License

package/package.json

@@ -1,42 +1,30 @@
 {
   "name": "opencode-buddy",
-  "version": "0.2.1",
-  "description": "A virtual ASCII pet companion for opencode. Works as a tmux sidecar or an in-TUI /buddy slash command.",
+  "version": "0.3.0",
+  "description": "A virtual ASCII pet companion that lives in the opencode TUI sidebar. Hatches, feeds, plays, and reacts to what you're coding.",
   "type": "module",
-  "main": "src/plugin.js",
+  "main": "src/server-plugin.js",
   "exports": {
-    ".": "./src/plugin.js",
-    "./cli": "./bin/opencode-buddy.js",
+    ".": "./src/server-plugin.js",
+    "./tui": "./src/tui-plugin.jsx",
     "./package.json": "./package.json"
   },
-  "bin": {
-    "opencode-buddy": "bin/opencode-buddy.js"
-  },
   "files": [
-    "bin",
     "src",
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "start": "node bin/opencode-buddy.js start",
-    "hatch": "node bin/opencode-buddy.js hatch",
-    "stats": "node bin/opencode-buddy.js stats",
-    "install-buddy": "node bin/opencode-buddy.js install",
-    "test": "node --test test/smoke.js test/plugin.smoke.js",
-    "test:e2e": "node test/e2e.js"
-  },
   "keywords": [
     "opencode",
     "opencode-plugin",
-    "tmux",
+    "tui",
     "pet",
     "tamagotchi",
     "ascii",
-    "tui",
     "companion",
     "buddy",
-    "virtual-pet"
+    "virtual-pet",
+    "sidebar"
   ],
   "engines": {
     "node": ">=18"

package/src/persistence.js

@@ -16,6 +16,13 @@ export async function load() {
   }
 }
 
+export async function save(state) {
+  await fs.mkdir(DIR, { recursive: true });
+  const tmp = FILE + ".tmp";
+  await fs.writeFile(tmp, JSON.stringify(state, null, 2));
+  await fs.rename(tmp, FILE);
+}
+
 export async function mtime() {
   try {
     const st = await fs.stat(FILE);
@@ -26,13 +33,6 @@ export async function mtime() {
   }
 }
 
-export async function save(state) {
-  await fs.mkdir(DIR, { recursive: true });
-  const tmp = FILE + ".tmp";
-  await fs.writeFile(tmp, JSON.stringify(state, null, 2));
-  await fs.rename(tmp, FILE);
-}
-
 export function pathForDisplay() {
   return FILE;
 }

package/src/server-plugin.js

@@ -0,0 +1,133 @@
+// v1 server plugin. Provides the `buddy` tool the LLM can call.
+// Loaded by opencode via package.json `main` (server-kind entrypoint).
+
+import { tool } from "@opencode-ai/plugin";
+import * as state from "./state.js";
+import * as persistence from "./persistence.js";
+import { SPECIES, renderFrame, maxFrameHeight } from "./species.js";
+
+const SPECIES_LIST = SPECIES.join(", ");
+
+const DESCRIPTION = `Interact with your virtual buddy companion. Pass an "action" argument.
+
+Actions:
+  status                  - print current stats as a one-liner
+  feed                    - feed the buddy (+25 hunger, -5 energy)
+  play                    - play with the buddy (+20 happiness, +5 xp)
+  rest                    - let the buddy rest (+30 energy)
+  switch <species>        - change species (${SPECIES_LIST})
+  rename <name>           - rename the buddy (max 20 chars)
+  hatch [species] [name]  - start a brand new buddy
+  ascii [frame]           - render the current buddy as ASCII art
+  help                    - list available actions
+
+The buddy lives in the opencode sidebar. Use this tool whenever the
+user wants to interact with their buddy.`;
+
+function summary(s) {
+  return `${s.name} the ${s.species} | Lv ${s.level} | ${s.state} | hunger ${Math.floor(s.hunger)} happiness ${Math.floor(s.happiness)} energy ${Math.floor(s.energy)} | xp ${s.xp}/${s.level * 50}`;
+}
+
+async function loadOrInit() {
+  const s = await persistence.load();
+  if (s) return s;
+  const fresh = state.hatch();
+  await persistence.save(fresh);
+  return fresh;
+}
+
+async function BuddyPlugin() {
+  return {
+    tool: {
+      buddy: tool({
+        description: DESCRIPTION,
+        args: {
+          action: tool.schema
+            .string()
+            .describe(
+              `One of: status, feed, play, rest, switch, rename, hatch, ascii, help. For switch/rename/hatch, also pass the "species" or "name" argument.`,
+            ),
+          species: tool.schema
+            .string()
+            .optional()
+            .describe(`Species for switch/hatch: ${SPECIES_LIST}`),
+          name: tool.schema
+            .string()
+            .optional()
+            .describe(`Name for rename/hatch (max 20 chars).`),
+          frame: tool.schema
+            .number()
+            .int()
+            .min(0)
+            .max(10)
+            .optional()
+            .describe(`Frame index for ascii action.`),
+        },
+        async execute(args) {
+          let s = await loadOrInit();
+          const action = (args.action || "").toLowerCase();
+          const species = (args.species || "").toLowerCase();
+          const name = args.name;
+          const frame = args.frame ?? 0;
+
+          switch (action) {
+            case "":
+            case "status":
+              return summary(s);
+            case "feed":
+              s = state.feed(s);
+              await persistence.save(s);
+              return `${s.name} munches happily. ${summary(s)}`;
+            case "play":
+              s = state.play(s);
+              await persistence.save(s);
+              return `${s.name} plays! ${summary(s)}`;
+            case "rest":
+              s = state.rest(s);
+              await persistence.save(s);
+              return `${s.name} curls up. ${summary(s)}`;
+            case "switch": {
+              if (!species) return `Pick a species: ${SPECIES_LIST}`;
+              if (!SPECIES.includes(species))
+                return `Unknown species "${species}". Valid: ${SPECIES_LIST}`;
+              s = state.switchSpecies(s, species);
+              await persistence.save(s);
+              return `${s.name} transformed into a ${species}. ${summary(s)}`;
+            }
+            case "rename": {
+              if (!name) return `Provide a name with the "name" argument.`;
+              s = state.rename(s, name);
+              await persistence.save(s);
+              return `Renamed to ${s.name}. ${summary(s)}`;
+            }
+            case "hatch": {
+              const sp = species && SPECIES.includes(species) ? species : "duck";
+              s = state.hatch({ species: sp, name: name || "Buddy" });
+              await persistence.save(s);
+              return `Hatched a new ${sp} named ${s.name}. ${summary(s)}`;
+            }
+            case "ascii": {
+              const lines = renderFrame(s.species, s.state, frame);
+              return [
+                "```",
+                ...lines,
+                "```",
+                `${s.name} the ${s.species} · ${s.state}`,
+                `hunger ${Math.floor(s.hunger)}  happy ${Math.floor(s.happiness)}  energy ${Math.floor(s.energy)}  xp ${s.xp}/${s.level * 50}`,
+              ].join("\n");
+            }
+            case "help":
+              return DESCRIPTION;
+            default:
+              return `Unknown action "${args.action}". Try: action=help`;
+          }
+        },
+      }),
+    },
+  };
+}
+
+export default {
+  id: "opencode-buddy",
+  server: BuddyPlugin,
+};