OpenCode Wife

繁體中文 · 简体中文 · Documentation

A Live2D companion for OpenCode Desktop — a fork-based presentation layer that gives your coding sessions a character that talks to you, without getting in the way of the work.

Alpha release — Windows x64 only. The installer is unsigned; see Installation. Side Chat is stable and useful today; Live2D rendering is optional and requires a runtime you install yourself (no proprietary files are bundled).

What you get

• Side Chat — a second, read-only conversation surface next to your main Agent session. Ask project questions while the agent works; the Wife session uses only read / glob / grep tools and can never write files or run commands.
• A Live2D character — attach your own model (.model3.json folder), bind its motions and expressions through a visual editor, and watch it react in a side panel.
• Easy-to-read bubbles — adjustable height, text size, reveal pacing, contrast, and motion; character header on every bubble.
• /send — turn the Side Chat into an editable Agent draft (Replace / Append / Cancel; never auto-submitted).
• /clear — permanently delete the current Wife conversation while keeping character, persona, model, and view preferences.
• Persona — per-character name, user address, and bounded speaking instructions, applied from the next reply.
• Reply choices — after each answer, 2–3 short follow-ups are generated by a separate low-cost model and rendered as buttons.

Screenshots

Reply choices	Send to Agent

How it relates to OpenCode

OpenCode Wife is a derivative product, not a fork that replaces OpenCode. The two apps can be installed side by side and share the same Agent data — but only one of them may run at a time:

• Sessions, projects, provider credentials, and Agent history are shared continuously.
• Wife-specific data (characters, persona, Live2D paths, Side Chat settings, window state) lives only in the Wife profile.
• When one app is running, launching the other focuses the running app instead of starting a second backend — two backends writing the same database are never allowed.
• A session closed in one app is immediately visible in the other; no import needed.

The Side Chat never pollutes your main Agent transcript. It is a separate archived session with a deny-all/read-only permission profile, so its replies and tools stay out of the agent's context.

Installation

1. Download the Windows x64 installer (opencode-wife-0.1.0-alpha.1-win-x64.exe) from the Releases page and verify the SHA-256 checksum.
2. The first release is unsigned: Windows SmartScreen shows a warning. Choose More info → Run anyway.
3. On first run, Wife offers to import safe UI preferences from an existing OpenCode profile (you can re-import anytime under Settings → Wife → OpenCode data).

First steps

1. Talk to the companion

Open a session, press mod+alt+w (or the Toggle Wife button in the title bar) to open the panel, and send a message. The character reads the current Agent context and answers with read-only tools.

Panel controls:

• Top-left character dropdown — switch which character is displayed for this session.
• Top-right mouse icon — enter Live2D model adjustment mode: drag to move the model, scroll to zoom (0.2x–3x). Chat UI pauses in this mode; press Escape or click the icon again to return to chat.
• Scroll wheel over the conversation — scroll up to reveal the detailed conversation history, scroll down to collapse back to the recent messages.

2. Set up a model and provider

• Main chat model: the Wife session shares your configured OpenCode provider/model.
• Choice generator: Settings → Wife → Reply choices — a separate low-cost model (default opencode/deepseek-v4-flash at low) that suggests follow-ups without delaying the answer.
• Persona: Settings → Wife → General — user address and speaking instructions.

3. Install the Live2D runtime

OpenCode Wife does not bundle live2dcubismcore.min.js or any sample model.

1. Settings → Wife → Live2D runtime → Download and install.
2. Wife downloads the compatible Core from the official Live2D CDN and verifies it (version and SHA-256 are recorded); downloading implies acceptance of the Live2D license terms.
3. Choose file… accepts an SDK ZIP or live2dcubismcore.min.js from an older SDK release.
4. Replace or remove the runtime at any time from the same screen.

Core compatibility: the bundled runtime requires a Cubism Core with the classic csmGetDrawableRenderOrders API. The latest Cubism 5 SDK release renamed it and is rejected with a clear message — use the official CDN file (https://cubism.live2d.com/sdk-web/cubismcore/live2dcubismcore.min.js) or an earlier SDK release instead.

A Live2D model is required for rendering: open Settings → Wife → Characters, add a character, and pick its model folder. The free official Hiyori sample is a good starting point — review its terms before use. Importing models is covered in the documentation.

Side Chat works fine without any of this — the panel just shows a setup state.

4. Commands

• /send — summarize the Side Chat into an editable Agent draft.
• /clear — delete the current Wife conversation.

Shared data, updates, and compatibility

• Shared Agent state: sessions, projects, and credentials are read from the same data root as OpenCode. Upgrade caution applies in both directions: after upgrading OpenCode, Wife may need a matching update, and vice versa.
• Compatibility guard: before starting, Wife checks the shared database schema. If OpenCode has upgraded to a schema Wife cannot read, Wife refuses to start with an actionable message — it never downgrades or modifies the database.
• Updates: Wife's automatic updater is disabled in this alpha. Check the Releases page manually. The bundled Agent backend never self-updates.
• Backups: a consistency backup of the shared database is kept before any schema-changing start (latest three retained).

Privacy and security

• The Wife session is read-only by construction: read / glob / grep tools only, no write or exec tools, no permission prompts. This is enforced by the server-side permission profile, not just hidden buttons.
• Your code, prompts, and conversations go to the LLM provider you configured — the same data flow as OpenCode.
• Live2D model files and the Cubism Core stay on your machine; nothing is uploaded.
• Alpha caveats: no automatic updates, unsigned installer, Windows x64 only. Report issues on the issue tracker; security issues via Private Vulnerability Reporting.

Building from source

bun install
bun run build          # packages/app
bunx electron-vite build  # packages/desktop
bun run package:win    # packages/desktop — Windows x64 NSIS installer

See docs/README.md for local setup notes and docs/12-handoff.md for environment quirks.

License and attribution

MIT — see LICENSE. OpenCode Wife is an independent derivative of OpenCode; see NOTICE.md for attribution and Live2D trademark/licensing notes.

Live2D and Cubism are trademarks of Live2D Inc. This project is not affiliated with or endorsed by Live2D Inc. Distributing this software does not imply that Live2D has approved its license classification — review the Live2D SDK license yourself.