Co-Ober

Co-Ober

Beta. Currently in public testing.

English | 中文

An Obsidian plugin that brings the OpenCode AI Agent into your vault as a living assistant. It understands your notes, explores your vault structure, and helps you think, write, and organize. All without leaving Obsidian.

Why Co-Ober

Most Obsidian AI plugins need third-party API keys (ongoing token costs) or middleware layers (extra token consumption). Co-Ober connects directly to your local OpenCode CLI, which provides free token quotas that cover most note-taking use cases. No API keys, no middlemen.

Features

Chat Sidebar: Open from the ribbon icon or command palette. Talk to the OpenCode Agent directly inside Obsidian with streaming responses rendered in real-time.

@mention Notes: Type @ to reference any note in your vault. The agent reads and understands your existing knowledge base, then answers, summarizes, or creates content based on it.

Tool Output as Notes: Sync rules write the results of the agent's tool calls (a file write, a search) straight into vault notes. No manual copy-paste for those. Your chat reply itself is only saved as a note when you ask the agent to write one.

Model & Mode Switching: Switch AI models and Agent modes (build / plan, or whatever the connected runtime offers) in the toolbar. Mode cycles on click; model opens a hover dropdown.

Custom Agents & Skills: Define local agent profiles and reusable skill instructions in Settings, then inject them into new chat prompts.

Streaming Response Rendering: Real-time rendering of Markdown, thinking blocks, tool calls (with filename display for read/write/edit operations), and plan panels.

Sync Engine: Tool call results (file edits, writes) are written back to Vault notes based on configurable sync rules with filename templates.

Permission Modes: Choose your control level: safe (confirm every action in a banner), readonly or plan (this client refuses file writes and command execution, whatever the capability settings allow), or yolo (auto-approve everything). Cycles on click with color-coded borders; in safe and yolo, a client-side change the agent performed without asking is recorded in the transcript.

Auto-Reconnect: Recovers automatically when the OpenCode process crashes.

i18n (Internationalization): Switch between English and Chinese UI in Settings > Appearance.

MCP Servers: Configure local MCP servers in Settings and attach them when creating or restoring OpenCode sessions.

Requirements

• OpenCode CLI installed and accessible
• Obsidian v1.8.0+
• Desktop only (macOS, Linux, Windows)

Installation

Manual

1. Download main.js, manifest.json, and styles.css from the latest release
2. Create a folder called co-ober in your vault's plugins folder:

   /path/to/vault/.obsidian/plugins/co-ober/
   

3. Copy the downloaded files into the co-ober folder
4. Enable the plugin in Obsidian: Settings → Community plugins → Enable "Co-Ober"

[!NOTE] Community plugin listing is pending review. For now, manual install is required.

From source (development)

1. Clone this repository into your vault's plugins folder:

   cd /path/to/vault/.obsidian/plugins
   git clone https://github.com/player-Muteki/co-ober.git
   cd co-ober
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Enable the plugin in Obsidian:
   • Settings → Community plugins → Enable "Co-Ober"

Configuration

Runtime agents, models, and available commands/skills load from an existing OpenCode connection or after an explicit reconnect. Opening Settings does not start OpenCode or create a metadata session.

Keyboard Shortcuts

Privacy & Data Use

• Sent to API: Your input, referenced notes, attached files/images, and tool call outputs. All communication goes through your local OpenCode CLI, which handles provider API calls.
• Local storage: Co-Ober settings and session data are stored in Obsidian's plugin data (data.json within .obsidian/plugins/co-ober/). Synced notes are created in your configured folder (default: opencode-sync/).
• No telemetry: Co-Ober does not send telemetry or analytics data. Network activity is limited to the OpenCode CLI subprocess communicating with AI providers.
• Environment: The OpenCode subprocess inherits the Obsidian process environment for PATH resolution and proxy configuration.

Troubleshooting

OpenCode CLI not found

If you see Failed to connect to OpenCode, the plugin can't locate the opencode executable.

Solution: Set the full path to opencode in Settings → OpenCode CLI Path.

Alternative: Add the directory containing opencode to your system PATH.

Session not persisting

Sessions are stored in Obsidian's plugin data. If sessions disappear after restart:

• Check that Obsidian has write access to the .obsidian/ directory
• Verify that session retention days is not set too low

Sync rules not creating notes

• The target folder is created when it is missing — check the path is not already taken by a file of the same name
• Check that the sync rule is enabled in Settings
• Verify the tool name matches the agent's tool call (e.g., edit, write)

Architecture

src/
├── main.ts                      # Plugin entry point, lifecycle, unified storage
├── settings.ts                  # Settings tab: connection, diagnostics, agent, sync, MCP, capability config
├── types.ts                     # Shared type definitions and defaults
│
├── client/                      # OpenCode Agent client layer
│   ├── acp.ts                   # ACP facade: sessions, prompts, permissions, capabilities, reconnect
│   ├── AcpJsonRpcTransport.ts   # JSON-RPC request/notification transport
│   ├── AcpSubprocess.ts         # Local OpenCode subprocess lifecycle
│   ├── agent.ts                 # Runtime wrapper: idle timeout and permission policy
│   ├── fsDelegate.ts            # Vault-bounded ACP fs/read_text_file and fs/write_text_file delegate
│   ├── terminalManager.ts       # ACP terminal create/output/kill/wait/release delegate
│   ├── sessionUpdateNormalizer.ts # Converts ACP updates into UI-friendly normalized events
│   └── index.ts                 # Module exports
│
├── view/                        # Sidebar chat view
│   ├── CoOberView.ts          # Obsidian ItemView: DOM composition, input, drag/drop, keybindings
│   ├── CoOberViewController.ts # Connection/session/send orchestration and UI state transitions
│   ├── renderer.ts              # Message rendering: markdown, tool calls, thinking blocks
│   ├── permissionBanner.ts      # Safe-mode permission prompts
│   ├── inlineEditPanel.ts       # Selection edit preview and apply UI
│   ├── sessionDropdown.ts       # Session switch/delete UI
│   └── welcomeView.ts           # Empty-state and capability-aware status UI
│
├── chat/                        # Chat input, toolbar, state, sessions, stream handling
│   ├── input.ts                 # Prompt input, send/stop, mention and slash triggers
│   ├── toolbar.ts               # Model/mode/effort/permission toolbar and usage meter
│   ├── chatState.ts             # Mutable chat view state
│   ├── session.ts               # Serialized session store backed by plugin data
│   └── streamController.ts      # Applies normalized stream updates, persistence, and sync hooks
│
├── context/                     # Vault context management
│   ├── mention.ts               # @mention note picker and resolution
│   ├── resolver.ts              # Resolve note/file references to content
│   └── injection.ts             # Build system prompt from BASE_IDENTITY + custom instructions
│
├── sync/                        # Sync engine: agent → vault
│   ├── engine.ts                # Execute sync rules, write tool results as notes
│   └── templates.ts             # Filename template rendering ({{tool}}, {{date}}, {{shortId}})
│
├── commands/                    # Slash command parsing and display helpers
├── agents/                      # Custom agent/skill prompt assembly
├── i18n/                        # Internationalization (EN/ZH locale dictionaries)
└── utils/                       # Cross-cutting utilities (vault path, etc.)

Roadmap

• OpenCode ACP integration
• @mention vault notes
• Sync engine with configurable rules
• Model and mode switching
• Inline edit (select text in note → AI edit with diff preview)
• MCP server support
• Custom agents and skills
• i18n (internationalization)
• Full slash command support (local + ACP routing)
• Enhanced @mention file support
• More planned.

License

Licensed under the MIT License.

Star History

Acknowledgments

• Obsidian for the plugin API
• OpenCode for the free AI Agent platform and ACP protocol

---

Co-Ober 中文说明

English | 中文

Beta，目前处于公开测试阶段。

将 OpenCode AI Agent 带入你的 Obsidian 仓库，成为一个住在 Vault 里的助手。它能理解你的笔记、探索仓库结构，帮你思考、写作和整理——全程不用离开 Obsidian。

为什么做 Co-Ober

现有的 Obsidian AI 插件大致分两类：需要自行配置第三方 API Key（长期产生 Token 费用）或依赖中间层中转（增加 Token 消耗）。Co-Ober 直连本地 OpenCode CLI，而 OpenCode 本身提供免费 Token 额度，对绝大多数笔记用户完全够用。无需 API Key，也无需中间层。直接使用，轻量，零成本。

功能特性

侧边栏对话：通过工具栏图标或命令面板打开。在 Obsidian 内直接与 OpenCode Agent 对话，流式响应实时渲染。

@提及 笔记：输入 @ 即可引用 Vault 中的任意笔记。Agent 能读取并理解你现有的知识库，然后基于笔记内容进行回答、总结或创作。

工具输出保存为笔记：同步规则会把 Agent 工具调用的结果（例如一次写文件、一次检索）直接写入 Vault 笔记，这类内容无需手动复制。聊天回复本身只有在你要求 Agent 写笔记时才会成为笔记。

模型与模式切换：在界面中直接切换 AI 模型和 Agent 模式（离线时为 build / plan，完整列表来自已连接的运行时）。

自定义 Agent 与技能：在设置中定义本地 Agent 配置和可复用技能指令，并注入到新的对话提示词中。

流式响应渲染：实时渲染 Markdown、思考块、工具调用（读写编辑操作显示具体操作的文件名）和计划面板。

同步引擎：工具调用结果（文件编辑、写入）根据可配置的同步规则和文件名模板，自动写回 Vault 笔记。

权限模式：选择控制级别：safe（每次操作都在横幅中确认）/ readonly 或 plan（无论能力设置如何，本客户端都拒绝写文件与执行命令）/ yolo（全部自动批准）。点击循环并显示不同颜色的边框；在 safe 与 yolo 下，agent 未经询问就完成的本地改动会记录在对话里。

自动重连：OpenCode 进程崩溃后自动恢复连接。

国际化（i18n）：在设置 → 外观中切换中英文界面。

MCP 服务器：在设置中配置本地 MCP 服务器，新建或恢复 OpenCode 会话时自动附加。

系统要求

• 已安装并可访问 OpenCode CLI
• Obsidian v1.8.0+
• 仅桌面端（macOS、Linux、Windows）

安装方式

手动安装

1. 从最新 Release 下载 main.js、manifest.json 和 styles.css
2. 在 Vault 的插件目录中创建 co-ober 文件夹：

   /path/to/vault/.obsidian/plugins/co-ober/
   

3. 将下载的文件复制到 co-ober 文件夹
4. 在 Obsidian 中启用插件：设置 → 第三方插件 → 启用 "Co-Ober"

[!NOTE] 社区插件市场审核中，当前仅支持手动安装。

从源码安装（开发）

1. 将仓库克隆到 Vault 的插件目录：

   cd /path/to/vault/.obsidian/plugins
   git clone https://github.com/player-Muteki/co-ober.git
   cd co-ober
   

2. 安装依赖并构建：

   npm install
   npm run build
   

3. 在 Obsidian 中启用插件：
   • 设置 → 第三方插件 → 启用 "Co-Ober"

配置说明

运行时 Agent、模型和可用命令/技能从已有的 OpenCode 连接中加载，或在手动重连后加载。打开设置页不会启动 OpenCode 或创建元数据会话。

键盘快捷键

隐私与数据

• 发送至 API：你的输入、引用的笔记、附加的文件/图片以及工具调用结果。所有通信都经过本地 OpenCode CLI，由它处理与 AI 提供商的 API 调用。
• 本地存储：Co-Ober 的设置和会话数据存储在 Obsidian 的插件数据中（.obsidian/plugins/co-ober/data.json）。同步的笔记保存在你配置的文件夹中（默认：opencode-sync/）。
• 无遥测：Co-Ober 不发送任何遥测或分析数据。网络活动仅限于 OpenCode CLI 子进程与 AI 提供商的通信。
• 环境变量：OpenCode 子进程继承 Obsidian 进程的环境变量，用于 PATH 解析和代理配置。

故障排除

找不到 OpenCode CLI

如果看到 Failed to connect to OpenCode，说明插件找不到 opencode 可执行文件。

解决方案：在设置 → OpenCode CLI 路径中填入 opencode 的完整路径。

替代方案：将包含 opencode 的目录添加到系统 PATH。

会话重启后丢失

会话存储在 Obsidian 的插件数据中。如果重启后会话消失：

• 检查 Obsidian 是否对 .obsidian/ 目录有写入权限
• 确认会话保留天数没有设置过低

同步规则没有创建笔记

• 目标文件夹缺失时会自动创建——请确认该路径没有被同名文件占用
• 检查设置中该同步规则是否已启用
• 确认工具名称与 Agent 的工具调用匹配（如 edit、write）

项目架构

src/
├── main.ts                      # 插件入口、生命周期管理、统一存储
├── settings.ts                  # 设置面板：连接、诊断、Agent、同步、MCP、能力配置
├── types.ts                     # 共享类型定义和默认值
│
├── client/                      # OpenCode Agent 客户端层
│   ├── acp.ts                   # ACP 门面：会话、提示词、权限、能力协商、重连
│   ├── AcpJsonRpcTransport.ts   # JSON-RPC 请求/通知传输
│   ├── AcpSubprocess.ts         # 本地 OpenCode 子进程生命周期
│   ├── agent.ts                 # 运行时包装：空闲超时和权限策略
│   ├── fsDelegate.ts            # 限定在 Vault 内的 ACP 文件读写委托
│   ├── terminalManager.ts       # ACP 终端创建、输出、终止、等待、释放委托
│   ├── sessionUpdateNormalizer.ts # 将 ACP 更新转换为 UI 友好的标准事件
│   └── index.ts                 # 模块导出
│
├── view/                        # 侧边栏对话视图
│   ├── CoOberView.ts          # Obsidian ItemView：DOM 组合、输入、拖拽、快捷键
│   ├── CoOberViewController.ts # 连接、会话、发送流程和 UI 状态编排
│   ├── renderer.ts              # 消息渲染：Markdown、工具调用、思考块
│   ├── permissionBanner.ts      # safe 模式权限确认 UI
│   ├── inlineEditPanel.ts       # 选区编辑预览和应用 UI
│   ├── sessionDropdown.ts       # 会话切换和删除 UI
│   └── welcomeView.ts           # 空状态和能力感知状态 UI
│
├── chat/                        # 对话输入、工具栏、状态、会话、流处理
│   ├── input.ts                 # 提示词输入、发送/停止、@ 和 / 触发
│   ├── toolbar.ts               # 模型、模式、effort、权限工具栏和用量仪表
│   ├── chatState.ts             # 对话视图可变状态
│   ├── session.ts               # 基于插件数据的序列化会话存储
│   └── streamController.ts      # 应用标准化流更新、持久化和同步钩子
│
├── context/                     # Vault 上下文管理
│   ├── mention.ts               # @提及笔记选择器和解析
│   ├── resolver.ts              # 将笔记/文件引用解析为实际内容
│   └── injection.ts             # 从 BASE_IDENTITY + 自定义指令构建系统提示词
│
├── sync/                        # 同步引擎：Agent → Vault
│   ├── engine.ts                # 执行同步规则，将工具结果写入笔记
│   └── templates.ts             # 文件名模板渲染（{{tool}}、{{date}}、{{shortId}}）
│
├── commands/                    # 斜杠命令解析和显示辅助
├── agents/                      # 自定义 Agent/技能提示词组装
├── i18n/                        # 国际化（中英双语词典）
└── utils/                       # 通用工具函数（Vault 路径等）

开发路线图

• OpenCode ACP 集成
• @提及 Vault 笔记
• 可配置规则的同步引擎
• 模型和模式切换
• 行内编辑（选中笔记文字 → AI 编辑并显示 Diff 预览）
• MCP 服务器支持
• 自定义 Agent 和技能
• 国际化（i18n）
• 斜杠命令满血适配（本地 + ACP 路由）
• @ 文件功能满血优化
• 更多功能规划中

许可证

本项目采用 MIT 许可证。

Star 历史

致谢

• Obsidian 提供的插件 API
• OpenCode 提供的免费 AI Agent 平台和 ACP 协议