opencode-studio

English | 简体中文

a local gui for managing opencode configurations. toggle mcp servers, edit skills, manage plugins, handle auth - no json editing required.

opencode v2 configuration support

The compatibility work targets OpenCode 2.1.4 while retaining supported v1 config editing. Studio preserves the source format instead of migrating your setup:

• Native agents and commands, including ordered permission rules and agent Markdown files; MCP’s servers, disabled, and global timeout settings.
• Native provider model maps and plugin package entries/options.
• Both v1 and v2 usage database layouts, with errors instead of false zero totals when a database cannot be read.
• A separate Raw Config → v2 CLI editor for global cli.json. It does not overwrite tui.json or silently prevent first-launch migration.

Important limits: v2 authentication is metadata-only in Studio. Use opencode auth for credential changes and account selection; legacy Studio auth pools are not applied to v2. V1 plugins need an actual API port, not a renamed config key. Native plugin runtime controls use plugin IDs, so edit those controls in Raw Config rather than relying on package-name toggles. Existing plugin code is never auto-converted.

See the compatibility verification notes and upstream migration guide. End-to-end native CLI agent discovery remains unverified; this is not a blanket compatibility claim. Keep a backup, and do not point v1 at native-v2-only configuration.

quickstart

option 1: public site + local backend (recommended)

npm install -g opencode-studio-server

visit opencode.micr.dev and click “Launch Backend” in the sidebar.

option 2: fully local

windows

quickstart.bat

macos / linux

chmod +x quickstart.sh && ./quickstart.sh

open http://localhost:1080

features

• mcp manager: toggle servers on/off, add new ones by pasting npx commands, delete unused configs
• profiles: isolated environments with separate configs, history, and sessions. switch instantly.
• skill editor: browse/edit skills, create from templates, import from url, bulk import multiple urls
• plugin hub: manage js/ts plugins, multiple templates (hooks, watchers, lifecycle), bulk import
• commands: browse and manage custom slash commands
• agents: manage custom agents with mode, model, tools, permissions (supports OMO format)
• usage dashboard: token costs, model breakdown, project stats from local message logs
• auth: login/logout per provider, save and switch between credential profiles
• github sync: push/pull config to a private github repo via gh cli
• backup/restore: export/import complete config including skills and plugins
• settings: general config, system prompt editor, oh my opencode model preferences
• i18n: internationalization support with Chinese (zh-CN) translation

i18n (Internationalization)

OpenCode Studio supports multiple languages:

• English (default)
• Chinese (zh-CN) - 完整中文翻译

Language can be switched via the language switcher in the sidebar. Selection is saved in cookies and persists across sessions.

To add a new language:

1. Create client-next/messages/{locale}.json (e.g., ja.json for Japanese)
2. Copy structure from en.json and translate all keys
3. Add locale to client-next/src/i18n/request.ts

how it works

1. detect: server finds your opencode config directory automatically
2. read: loads opencode.json, skills, plugins, auth
3. edit: make changes through the ui
4. save: writes back to disk instantly

usage

bulk import

paste multiple raw github urls (one per line):

https://raw.githubusercontent.com/.../skills/brainstorming/SKILL.md
https://raw.githubusercontent.com/.../skills/debugging/SKILL.md
https://raw.githubusercontent.com/.../skills/tdd/SKILL.md

click fetch → preview with checkboxes → existing items unchecked → import selected

deep links

opencode studio supports deep links for one-click installs from external sites.

note: github blocks custom protocols like opencodestudio:// in user content. use a redirect page on github pages to bypass this.

examples

add mcp server button (for docs/repos):

<a href="https://github.com/Microck/opencode-studio">
  <img src="https://img.shields.io/badge/opencode-studio-brown" alt="Add with OpenCode Studio" />
</a>

import skill button:

<a href="opencodestudio://import-skill?url=https%3A%2F%2Fraw.githubusercontent.com%2F...%2FSKILL.md">
  Import Skill
</a>

with environment variables:

opencodestudio://install-mcp?name=api-server&cmd=npx%20-y%20my-mcp&env=%7B%22API_KEY%22%3A%22%22%7D

url encoding

parameters must be url-encoded:

• spaces → %20
• / → %2F
• : → %3A
• { → %7B
• } → %7D

security

when clicking deep links, users see a confirmation dialog showing the command or url and a warning about trusting the source.

project structure

opencode-studio/
├── client-next/           # next.js 16 frontend
│   ├── src/app/           # pages (mcp, profiles, skills, plugins, auth, settings, usage)
│   ├── src/components/    # ui components
│   ├── src/i18n/          # internationalization config
│   ├── messages/          # translation files (en.json, zh-CN.json)
│   └── public/            # static assets
├── server/
│   └── index.js           # express api
├── quickstart.bat
├── quickstart.sh
└── package.json           # runs both with concurrently

config locations:

• opencode config: ~/.config/opencode/
• studio data: ~/.config/opencode-studio/
• profiles: ~/.config/opencode-profiles/

troubleshooting

sponsorship

sponsorships are welcome. contact [email protected] to discuss supporting the project.

license

mit