open-workspace

Multi-root workspace support for OpenCode and Claude Code, enabling VS Code .code-workspace file parsing and cross-directory operations.

Why

AI coding assistants typically operate in a single project directory. If your codebase spans multiple repositories (monorepo siblings, mobile + web + backend, etc.), you can't search or read across them natively. This plugin bridges that gap by leveraging the same .code-workspace files VS Code uses.

Install

建议使用 npm 上的包 + npx：无需克隆仓库，也不必手写本机 dist/server.js 路径。包名：open-workspace（当前版本可用 npm view open-workspace version 查看）。

MCP Server（Claude Code + OpenCode）— 推荐

需要 Node.js 18+。MCP 走的是包内 bin 入口（open-workspace → dist/server.js）。

Claude Code

claude mcp add open-workspace -- npx -y open-workspace@latest

或在项目根目录 .mcp.json：

{
  "mcpServers": {
    "open-workspace": {
      "command": "npx",
      "args": ["-y", "open-workspace@latest"],
      "env": {
        "WORKSPACE_DIR": "/path/to/your/project"
      }
    }
  }
}

OpenCode（opencode.json / opencode.jsonc）

{
  "mcp": {
    "open-workspace": {
      "type": "local",
      "command": ["npx", "-y", "open-workspace@latest"],
      "enabled": true,
      "environment": {
        "WORKSPACE_DIR": "/path/to/your/project"
      }
    }
  }
}

Note: WORKSPACE_DIR 可选；省略时使用当前工作目录。首次 npx 拉包会略慢，之后会复用缓存。

固定版本（可选）

将 open-workspace@latest 换成 open-workspace@0.2.1 等，避免次版本自动升级。

从源码运行 MCP（不推荐日常）

若你已克隆本仓库并完成 npm install && npm run build：

claude mcp add open-workspace -- node /absolute/path/to/open-workspace/dist/server.js

OpenCode 原生插件（不按 MCP）

与 MCP 二选一即可；插件走 @opencode-ai/plugin，不启动独立 MCP 进程。

npm install open-workspace

{
  "plugin": ["open-workspace"]
}

Skills（斜杠命令：OpenCode 与 Claude Code）

三套技能（ows:select / ows:search / ows:read）共用本仓库 skills/ 下同一批 SKILL.md。技能正文依赖 workspace_* MCP 工具，请先完成上文 MCP Server 配置，再装技能。

Claude Code 技能约定：每个技能是独立目录，内含 SKILL.md；个人级路径为 ~/.claude/skills/<目录名>/SKILL.md（目录名不必与 frontmatter 里 name 相同，斜杠命令以 name 为准，如 /ows:select）。

OpenCode

安装 同一 npm 包 后，将包内整个 skills 目录链到 OpenCode 技能目录（全局或项目本地均可）。

全局安装：

npm install -g open-workspace
ln -sf "$(npm root -g)/open-workspace/skills" ~/.config/opencode/skills/open-workspace

仅装在当前项目：

npm install open-workspace
ln -sf "$(pwd)/node_modules/open-workspace/skills" ~/.config/opencode/skills/open-workspace

改完后重启 OpenCode。也可从本仓库 skills/ 用 ln -s 指向同一结构。

Claude Code

OpenCode 是「整个 skills 目录一并链接」；Claude Code 需要 skills 下每个子目录（select、read、search）分别出现在 ~/.claude/skills/（或项目内 .claude/skills/）下，每个子目录里已有 SKILL.md。

全局安装（推荐与 npm install -g open-workspace 配合，路径与包版本一致）：

npm install -g open-workspace
OWS="$(npm root -g)/open-workspace/skills"
mkdir -p ~/.claude/skills
ln -sfn "$OWS/select" ~/.claude/skills/open-workspace-select
ln -sfn "$OWS/search" ~/.claude/skills/open-workspace-search
ln -sfn "$OWS/read"   ~/.claude/skills/open-workspace-read

仅当前项目（在已执行 npm install open-workspace 的目录中）：

OWS="$(pwd)/node_modules/open-workspace/skills"
mkdir -p .claude/skills
ln -sfn "$OWS/select" .claude/skills/open-workspace-select
ln -sfn "$OWS/search" .claude/skills/open-workspace-search
ln -sfn "$OWS/read"   .claude/skills/open-workspace-read

从本仓库源码链接时，将 OWS 设为克隆目录下的绝对路径，例如 OWS="/path/to/open-workspace/skills"，再把上面三条里的 OWS=... 换成该路径后执行 ln -sfn（目标目录可改为 ~/.claude/skills/... 以实现个人级安装）。

新开或重启 Claude Code 会话后，可使用 /ows:select、/ows:search、/ows:read。SKILL.md 中的 user-invocable 等字段主要为 OpenCode 使用；Claude Code 会按 Agent Skills 约定识别 name、description 等，未知字段一般忽略。

维护者

发布流程、npm 令牌与 GitHub Actions（NPM_TOKEN、Release 发版等）见 docs/MAINTAINERS.md。

从源码参与开发

git clone https://github.com/FuDesign2008/open-workspace.git
cd open-workspace
npm install
npm test
npm run build

npm test        # Vitest
npm run test:watch

测试覆盖 parser、state、workspace-tool-core（临时目录下的 list / select / read / grep / glob 等）。

Setup

Create a .code-workspace file in your project root (or use an existing one from VS Code):

{
  "folders": [
    { "path": "../bulb" },
    { "path": "../ydoc" },
    { "path": "../ynote-desktop" },
    { "path": "../ynote-android" },
    { "path": "../ynoteios" }
  ],
  "settings": {}
}

Folder paths are resolved relative to the .code-workspace file location.

Tools

6 tools are available, all prefixed with workspace_:

workspace_list

Find all .code-workspace files in the current project directory.

workspace_select

Select a workspace as the active one for the current session. Once selected, other tools use it automatically without needing the workspace parameter each time.

workspace_select                            # show current selection and available workspaces
workspace_select workspace="bulb-one"       # select by name
workspace_select workspace="clear"          # deselect

When only one .code-workspace file exists, it is auto-selected.

workspace_parse

Parse a workspace file and show all configured folders with their resolved paths.

workspace_read

Read a file from a specific workspace folder. Supports offset and limit for large files.

workspace_read folder="bulb" file="src/index.ts"

workspace_grep

Search file contents across all (or selected) workspace folders using regex.

workspace_grep pattern="useState" include="*.tsx"
workspace_grep pattern="export default" folders="bulb,ydoc"

workspace_glob

Find files by name pattern across all (or selected) workspace folders.

workspace_glob pattern="*.config.*"
workspace_glob pattern="package.json" folders="bulb,ydoc"

Skills (slash commands)

The package ships with 3 skills (SKILL.md under skills/). In OpenCode they register as user-invocable slash commands; in Claude Code they follow Claude Code skills discovery under ~/.claude/skills/ (see Skills（斜杠命令：OpenCode 与 Claude Code） above).

Skill	Trigger phrases	What it does
ows:select	"select workspace", "switch workspace"	Choose which .code-workspace to use
ows:search	"search workspace", "grep workspace"	Search file contents or find files by name
ows:read	"read workspace file"	Read files from any workspace folder

After linking, restart the client (or start a new session). Commands: /ows:select, /ows:search, /ows:read.

Architecture

src/
  server.ts                # MCP Server entry (stdio transport, registers all 6 tools)
  index.ts                 # OpenCode plugin entry (backward compatible)
  workspace-tool-core.ts   # Shared workspace_* behavior (list/select/parse/read/grep/glob)
  parser.ts                # .code-workspace JSONC parser
  state.ts                 # Session state (active workspace)
  tools/                   # OpenCode tool wrappers (thin; delegate to workspace-tool-core)

The MCP Server (server.ts) and OpenCode plugin (index.ts) share the same behavior via workspace-tool-core.ts (parser.ts, state.ts), and expose tools through different protocols.

License

MIT