opencode-studio

English | 简体中文

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

---

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

flowchart LR
    A[Browser] -->|HTTP| B(Express API :1920+)
    B -->|Read/Write| C[~/.config/opencode/]
    C --> D[opencode.json]
    C --> E[skill/]
    C --> F[plugin/]

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

route	actions
/mcp	toggle switches, add via npx command, search/filter
/profiles	create/switch isolated environments
/skills	create from template, bulk import, edit in monaco
/plugins	pick template, bulk import, click to edit
/commands	browse custom slash commands
/agents	manage agents with model, tools, permissions
/usage	token costs, model breakdown, project stats
/auth	login/logout, save/switch credential profiles
/settings	general, system prompt, github sync, oh my opencode models

---

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.

protocol	description
opencodestudio://launch	start backend only
opencodestudio://launch?open=local	start backend + open localhost:1080+
opencodestudio://install-mcp?name=NAME&cmd=COMMAND	install mcp server
opencodestudio://import-skill?url=URL	import skill from url
opencodestudio://import-plugin?url=URL	import plugin from url

examples

add mcp server button (for docs/repos):

import skill button:

  Import Skill

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

problem	fix
"opencode not found"	ensure ~/.config/opencode/opencode.json exists
port conflicts	both services auto-detect available ports (backend 1920+, frontend 1080+)
skills not showing	check ~/.config/opencode/skill/ has SKILL.md files
bulk import fails	ensure urls are raw github links
"Launch Backend" not working	run npm install -g opencode-studio-server first
protocol handler not registered	run opencode-studio-server --register as admin
github sync not working	run gh auth login first
agents not showing