Repository navigation
Releases
@mark_future_ai/opencode-buddy v1.1.2
@mark_future_ai/opencode-buddy v1.1.2
Floating pet
- New 48×48 pixel-art built-in pets: duck, cat, dragon, axolotl, robot, ghost.
- Smaller eyes, cleaner outlines, five expressions, and per-state animations.
- Custom Codex pet packs still import directly from
~/.codex/pets/.
Hide / restore
- Hiding the pet from the right-click menu now tells you how to bring it back.
- New composer slash command:
/buddy-pettoggles the floating pet. - The command palette entry Toggle floating pet still works.
Install
Requires OpenCode 2.2.6+.
npm install -g @mark_future_ai/opencode-buddyRestart OpenCode Desktop after upgrading.
@mark_future_ai/opencode-buddy v1.1.0
@mark_future_ai/opencode-buddy v1.1.0
The buddy now lives in OpenCode Desktop as a floating pet, while the TUI
sidebar keeps working.
Floating Desktop pet
- SVG/CSS pet floats over the Desktop window: drag to move, click for stats,
right-click for feed / play / rest / rename / switch. - Six built-in presets: duck, cat, dragon, axolotl, robot, ghost.
- Work state drives the animation: idle, working, celebrating, scared, and
sleeping. - Show or hide with the right-click menu or the command palette:
Toggle floating pet (Cmd+K/Ctrl+K). - Position and visibility are remembered.
Custom pet packs
- Loads community packs in the Codex pet format (
pet.json+
spritesheet.webp). - Auto-detects
~/.codex/pets/<id>/(read-only) and
~/.config/opencode-buddy/pets/<id>/. - Spritesheet: 8×9 atlas, 192×208 px cells, WebP/PNG/GIF up to 5 MB.
- Switch packs from the right-click menu → Pets; Built-in returns to
the six presets. - Custom packs are Desktop-only; the TUI keeps the built-in ASCII species.
Under the hood
- Server-side progression (
ctx.event.subscribe) now owns prompt/tool/turn
events, so Desktop-only sessions gain XP even when the TUI is not running. - Added
./gui-experimental(prebuilt CJS) and a Vite build. - The TUI part no longer subscribes to events; it renders the shared state.
Install
Requires OpenCode 2.2.6+.
npm install -g @mark_future_ai/opencode-buddyThen open OpenCode Desktop and reload the window. In the TUI the buddy appears
in the sidebar as before.
@mark_future_ai/opencode-buddy v1.0.0
@mark_future_ai/opencode-buddy v1.0.0
What's in this release
opencode-buddy now uses the OpenCode 2 plugin API (@opencode/plugin 2.2.6+). The buddy renders in the same sidebar slot and every existing buddy state file keeps working, but the plugin implementation is a full port: V1 plugin functions no longer run in OpenCode 2, so this release drops OpenCode 1 support.
Breaking changes
- Requires OpenCode 2.2.6+, including OpenCode Desktop 2.2.6+.
- The plugin is registered under
pluginsin~/.config/opencode/opencode.json. The oldtui.jsonentry and the V1pluginkey are no longer used. npm install -g @mark_future_ai/opencode-buddystill registers the plugin automatically. Upgrading users should remove the oldpluginentry fromopencode.jsonand the entry fromtui.json.- Node 18+ is unchanged.
Migration details
- Server part:
buddytool registered throughctx.tool.transformwith a JSON Schema input and structured{ content }results. - TUI part:
Plugin.define+setup(context); sidebar claim moved to thesidebar.contentslot; slash commands moved tocontext.keymap.layer; rename/switch dialogs use the promise-basedui.dialogAPI; theme colors use the V2 semantic tokens. - Events: subscriptions moved to the V2 event stream —
session.execution.started/succeeded/failed,session.tool.input.started/success/failed,session.shell.ended,session.compaction.ended,permission.replied,filesystem.changed, andvcs.branch.updated. - Todo xp removed: OpenCode 2 no longer emits the todo event the V1 plugin used (+5 xp per completed todo). All other xp and reward sources are unchanged.
- Cleanup: timers and event subscriptions are released through the cleanup function returned by
setup.
Fix
- A truncated or corrupt session file no longer breaks every buddy action. The bad file is renamed to
<id>.json.corruptand the session starts with a fresh buddy.
Install
npm install -g @mark_future_ai/opencode-buddyThe buddy appears in the sidebar on the next OpenCode start.
v0.6.2
Patch:
- LRU sweep now deletes session files instead of moving them to an
archive/folder (the archive was a half-measure — files still occupied disk and nothing ever cleaned the archive itself). - Threshold shortened from 30 days to 14 days.
- Renamed
ARCHIVE_AFTER_MS→IDLE_DELETE_MSto reflect the new behavior.
After 14 days of inactivity a session's buddy is gone for good.
v0.6.1
Patch: strip the redundant ses_ prefix from sessionIDs shown in /buddy-list (and the LLM tool's action=list) so each buddy fits on one line. 8 chars after the prefix → 6 chars after stripping.
v0.6.0 — Per-session buddy state with LRU archiver
opencode-buddy v0.6.0
What's in this release
Each opencode session now has its own buddy. Open a session, work for a while, close it — next time you open that session, the same buddy is there with the stats you left it at. Open a different session and you meet a different buddy. Buddy state moved from a single global file to per-session files under ~/.config/opencode-buddy/sessions/, with an LRU archiver to keep the directory from growing without bound.
Highlights
Per-session storage
- Before: one global
state.json. Every opencode window in the same user account shared a single buddy, fighting over xp. - After:
~/.config/opencode-buddy/sessions/<sessionID>.json. Each session has an independent buddy. Reopen the same session and the buddy is exactly as you left it.
State file location:
~/.config/opencode-buddy/
├── sessions/
│ ├── __default__.json
│ ├── abc-123.json
│ └── def-456.json
└── archive/ # session files idle > 30 days
Automatic backward-compatible migration
On first load, if a legacy state.json exists at the old location it is automatically renamed to sessions/__default__.json (a synthetic fallback session used when no opencode session is in scope — e.g. from the LLM tool with no session argument). The old file is removed after migration.
LRU archiver
A background timer runs once on plugin load and once per day. Session files whose idleAt is older than 30 days are moved from sessions/ to archive/. They remain on disk (cheap; ~500 bytes per file) and can be hand-restored, but no longer appear in listings or take up the active set.
- 100 active sessions = ~50 KB
- 10 000 archived sessions = ~5 MB
New slash command: /buddy-list
Lists every active session buddy with its name, species, and level. The current session's buddy is marked with →.
→ Quack the duck Lv3 (abc-123)
· Rex the dragon Lv1 (def-456)
· Buddy the cat Lv2 (ghi-789)
buddy LLM tool: optional session argument
The LLM can now target a specific session's buddy by passing session=<sessionID> to the buddy tool. Without it, the tool falls back to the __default__ synthetic session. A new action=list returns a summary across all session buddies.
Events without sessionID routed sensibly
Two opencode events don't carry a sessionID (file.edited and vcs.branch.updated). Rather than drop them, the plugin tracks the most recently active session and applies the bonus there. With per-session storage this is the right model — you can only be "in" one session at a time per TUI.
Full changelog since v0.5.0
src/persistence.js — rewritten
- New directory
~/.config/opencode-buddy/sessions/; per-session files<key>.json load(sessionID),save(sessionID, state),mtime(sessionID)— all take a session keysave()auto-bumpsidleAt: Date.now()on every write- Path sanitization: only
[A-Za-z0-9_-]{1,128}accepted as-is; anything else hashed to a stable hex key sweep(maxAgeMs): moves idle files toarchive/listSessions(): returns{sessionID, name, species, level, idleAt}[]sorted by recency- Legacy
state.jsonauto-migrates on first read
src/state.js
DEFAULT_STATEandhatch()initializeidleAt: Date.now()
src/tui-plugin.jsx
mutate(sessionID, fn)takes sessionID first; all event handlers and slash commands pass it through- View is keyed by sessionID; the slot re-renderer keeps a per-session View cache
- Slash commands read the current session from
api.route.current.params.sessionID(fallback__default__) lastActiveSessionIDtracked for events without sessionID (file.edited,vcs.branch.updated)- Idle-recovery timer now iterates all sessions in
listSessions()(not just one), giving inactive sessions a chance to recover - LRU sweep timer: runs at boot, then every 24h
/buddy-listcommand +buddy.listpalette entry
src/server-plugin.js
buddytool accepts optionalsession: stringargument- New
action=listreturns all session buddies
Install / upgrade
npm install -g opencode-buddy
# restart opencodeThe postinstall registers the plugin in ~/.config/opencode/opencode.json and ~/.config/opencode/tui.json as before. On first launch, the existing global state.json (if any) is migrated to sessions/__default__.json automatically.
Requires opencode ≥ 1.15.
License
MIT
v0.5.0 — Work-driven xp & balanced metabolism
opencode-buddy v0.5.0
What's in this release
The buddy is now driven by what you actually do in opencode, not just slash commands. Submit a prompt and the buddy starts working; finish a turn and it earns xp; long-idle and it naps to recover energy. 10+ new event hooks bind the buddy's state machine to opencode's live session events, with a balanced metabolism so stats actually drift over time instead of monotonically decaying.
Highlights
Work-driven progression (xp comes from coding)
/buddy-play no longer gives meaningful xp (+1 instead of +5). Instead, every real session event feeds the buddy:
| Trigger | Reward |
|---|---|
Prompt submitted (session.next.prompted) |
enter working state, mark lastPromptAt |
Tool call succeeds (session.next.tool.success) |
per-tool xp (read=1, edit/write/bash=3, others=2), +0.2 happy |
| 3 consecutive successes without failure | +5 xp streak bonus |
| Same tool called >5 times in one turn | xp halved (anti-grind) |
| Tool fails | -1 happy, -0.5 energy, streak reset; 2+ failures in a turn → scared |
Todo completed (todo.updated) |
+5 xp per item |
Turn complete (session.idle) |
base +10 xp + accumulated (cap 30), celebrating for 3s, toast surfaces "Turn complete +N xp" or "Level up!" |
Reward events (the buddy actually gets fed)
Previously the buddy could only be fed via /buddy-feed. Now coding feeds it too:
| Event | Effect |
|---|---|
File edited (file.edited) |
+1 hunger (30s global throttle) |
Shell command finished (session.next.shell.ended) |
+1 hunger, +1 energy |
Permission granted (permission.replied once/always) |
+3 hunger, +1 happy |
Git branch switched (vcs.branch.updated) |
+3 hunger, +1 happy |
Session history compacted (session.compacted) |
+10 energy, +2 happy |
| Idle >5 min, no prompt | +5 energy (5 min cooldown) |
| Level up | +5 hunger, +3 energy, +3 happy |
Circadian rhythm + sleep recovery
- Sleeping (when energy < 20) now recovers
+1 energy/mininstead of draining. The buddy heals itself if you walk away. - Late night (23:00–05:00 local) drains energy 1.5× faster — the buddy gets tired with you.
Rebalanced metabolism
Natural decay slowed down and turn costs cut roughly in half so stats actually float in a healthy range instead of free-falling:
| Stat | Before (per min) | After |
|---|---|---|
| hunger decay | -0.5 | -0.3 |
| happiness decay | -0.3 | -0.2 |
| energy decay | -0.2 | -0.15 |
| Stat (per turn) | Before | After |
|---|---|---|
| hunger cost | -3 to -13 | -2 to -8 |
| energy cost | -2 to -12 | -1 to -7 |
| happiness reward | +5 −2·fail | +1 −1·fail |
Slash commands stay strong (/buddy-feed +25 hunger, /buddy-rest +30 energy) so they remain useful when things really drop.
Verified balance
Simulated five usage profiles, starting 80/80/100 (hunger/happy/energy):
| Scenario | hunger | happy | energy | level |
|---|---|---|---|---|
| Light 1h (3 prompt × 3 tools) | 67 | 79 | 89 | Lv2 |
| Medium 1h (6 prompt × 5 tools) | 75 | 80 | 88 | Lv3 |
| Heavy 1h (12 prompt × 8 tools) | 96 | 84 | 81 | Lv4 |
| Heavy 4h | 96 | 82 | 8 (auto-sleeps to recover) | Lv8 |
| Medium 8h workday | 54 | 66 | 0 (time to /buddy-rest) | Lv7 |
Stats now actually drift up and down — no more single-direction decay, no more happiness pinning at 100.
Full changelog since v0.4.0
State machine (src/state.js)
- New:
awardXp,onPromptStart,onToolSuccess,onToolFailure,onTurnDone(state, xp, stats),onTodoCompleted,onFileEdited - New:
onPermissionAllowed,onShellSuccess,onBranchUpdated,onCompacted,onIdleRecovery,onStreak - New:
toolXp(name)weight table (read=1, glob=1, edit/write/bash=3, default=2) tick: sleeping now recovers energy; night-hours multipliermaybeLevelUp: now grants +5 hunger / +3 energy / +3 happyplay: xp +5 → +1, happy +20 → +15
TUI plugin (src/tui-plugin.jsx)
- In-memory
turnAccumper session: tracks xp, tools, failures, streak, per-tool counts - New event hooks:
session.next.prompted,session.next.tool.called,session.next.tool.success,session.next.tool.failed,todo.updated,file.edited,permission.replied,session.next.shell.ended,vcs.branch.updated,session.compacted - Idle-recovery timer polls every 60s, grants
+5 energyafter 5 min without a prompt - Streak detection: every 3rd consecutive tool success triggers
onStreak - Anti-grind: same tool used >5 times in a turn → weight halved
session.idlesettlement is atomic (single load + single save), surfacesLevel up!orTurn complete +N xptoast- Per-turn xp hard cap of 30 to prevent runaway sessions
Install / upgrade
npm install -g opencode-buddy
# restart opencodeRequires opencode ≥ 1.15.
License
MIT
v0.4.0 — Visible animation + Windows install fix
opencode-buddy v0.4.0
What's in this release
The buddy is now visibly alive in the sidebar — a real frame-by-frame animation system replaces the previous static art, every species sways with idle motion, and the dragon got a full redesign. Plus a Windows install fix and a screen-recorded demo in the README.
Highlights
Visible animation in the sidebar
Earlier releases technically had multiple frames, but solid-js never re-rendered the <text> rows inside the slot so you only ever saw frame 0. This release rebuilds the animation pipeline:
- A plugin-level frame signal drives the timer once per buddy, not once per render. Re-renders no longer reset the loop, and the loop is paused when the buddy is
sleeping(no wasted ticks). - Each ASCII row is a fixed
<text>element instead of a<For>list, so solid actually re-renders them on every frame. - The
Viewelement is cached across slot re-renders, so opencode swapping the slot contents doesn't recreate the buddy and restart the animation. - Idle body sway widened to 2 columns so motion is obvious at sidebar width.
End result: the buddy actually moves. See the GIF at the top of the README.
Dragon redesign + per-species idle motion
- The dragon was reworked from scratch — new silhouette, more readable at sidebar width.
- Every species (duck, cat, dragon, axolotl, robot, ghost) now has explicit per-frame body motion, not just blink/mouth animation.
Cross-platform fix — Windows install no longer crashes
postinstall used fs.rename to swap the new config in. On Windows, rename fails when the destination already exists (POSIX semantics differ). Replaced with a copy + unlink fallback so global install works on Windows too.
README demo
A short screen recording is now embedded inline at the top of the README. Iterated from mp4 → trimmed mp4 → 852 KB GIF so it previews directly on the GitHub repo page without a download.
Full changelog since v0.3.4
Animation system
feat(anim): make buddy visibly animate in sidebarfeat(anim): increase idle body sway to 2 columnsfix(anim): replaceForwith fixed<text>elements so each row re-rendersfix(anim): cache the View element so slot re-renders don't recreate itfix(anim): usecreateEffectwithsetTimeoutloop for animationfix(anim): drive frame from plugin-level timer, pause when sleeping
Art
feat(art): redesign dragon + add visible body motion to all species
Reactive (explored, then reverted)
feat(reactive): buddy reflects live LLM activityrevert: drop reactive LLM activity tracking, keep simple persisted states (kept the codebase minimal —session.idle/session.errorreactions from 0.3.4 are still in)
Cross-platform
fix:fs.renamefails on Windows when destination exists
Docs
docs: refresh README for 0.3.7 architecture (plugin-level frame signal)docs: add screen-recording demo to READMEdocs: switch demo to inline-previewable mp4 (8.4MB) → trimmed to 20s (2.3MB) → final 852 KB GIF
Install / upgrade
npm install -g opencode-buddy
# restart opencodeThe postinstall script registers the plugin in both ~/.config/opencode/opencode.json and ~/.config/opencode/tui.json. JSONC files with comments are left alone — add manually:
// ~/.config/opencode/opencode.json
{ "plugin": ["opencode-buddy"] }// ~/.config/opencode/tui.json
{ "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-buddy"] }Requires opencode ≥ 1.15.
License
MIT
v0.3.4
"# opencode-buddy v0.3.4\n\n## What's in this release\n\nTUI plugin with full sidebar integration. The buddy now lives natively in the opencode TUI sidebar — no tmux, no separate process.\n\n### Slash commands\n\n| Command | Effect |\n| --- | --- |\n| /buddy-feed | Feed the buddy (+25 hunger, -5 energy) |\n| /buddy-play | Play with the buddy (+20 happiness, +5 xp, -5 hunger) |\n| /buddy-rest | Let the buddy rest (+30 energy) |\n| /buddy | Show current stats as a toast |\n| /buddy-rename | Rename (max 20 chars, opens prompt dialog) |\n| /buddy-switch | Switch species (opens picker, 6 options) |\n\nSlash commands update state directly without going through the LLM — instant feedback.\n\n### Auto-reactions\n\n- session.idle → 4 second celebrating animation\n- session.error → 5 second scared animation\n- Energy < 20 → auto-transition to sleeping\n- Hunger < 25 → auto-transition to scared for 30s\n\n### Postinstall\n\nnpm install -g opencode-buddy now auto-registers the plugin in both ~/.config/opencode/opencode.json and ~/.config/opencode/tui.json. Skip-safe: leaves JSONC files with comments alone.\n\n### Bug fix since 0.3.3\n\nTUI plugin install was failing with NpmInstallFailedError: An unknown git error occurred. Root cause: npa(\"opencode-buddy/tui\") interprets the spec as a git URL (github:opencode-buddy/tui). The fix: use the same opencode-buddy spec in both configs. opencode's resolvePackageEntrypoint reads the package's exports field and picks the right entry based on runtime kind (server vs tui), so the same spec serves both purposes.\n\n## Install\n\nbash\nnpm install -g opencode-buddy\n# restart opencode\n\n\nThe postinstall handles the two config files. If you use JSONC with comments, add the entry manually:\n\njsonc\n// ~/.config/opencode/opencode.json\n{ \"plugin\": [\"opencode-buddy\"] }\n\n\njson\n// ~/.config/opencode/tui.json\n{ \"$schema\": \"https://opencode.ai/tui.json\", \"plugin\": [\"opencode-buddy\"] }\n\n\nRequires opencode ≥ 1.15.\n\n## Architecture\n\nmermaid\nflowchart LR\n User[Opencode TUI user]\n Prompt[Prompt]\n Sidebar[Sidebar]\n Keymap{{keymap}}\n Slots{{slot registry}}\n\n subgraph opencode-runtime[\"opencode TUI\"]\n Keymap\n Slots\n end\n\n subgraph buddy[\"opencode-buddy package\"]\n TuiEntry[tui entry]\n View[View component]\n SlashCmds[slash commands]\n end\n\n StateFile[(\"~/.config/opencode-buddy/state.json\")]\n\n User -->|types /buddy-feed| Prompt\n Prompt --> Keymap\n Keymap --> SlashCmds\n SlashCmds -->|read+write| StateFile\n\n Slots -->|invokes renderer| View\n View -->|render frame| Sidebar\n View -->|reads mtime| StateFile\n\n classDef store fill:#1e293b,stroke:#64748b,color:#f1f5f9\n class StateFile store\n\n\n## License\n\nMIT\n"
Release-26.06.04
v0.3.3 v0.3.3: postinstall auto-registers plugin config