Copsilot

Copsilot

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 Copsilot

Most Obsidian AI plugins need third-party API keys (ongoing token costs) or middleware layers (extra token consumption). Copsilot 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.

Auto-Save Output as Notes: AI-generated content saves directly to your local Vault via the sync engine. No manual copy-paste.

Model & Mode Switching: Switch AI models and Agent modes (build / plan / docs) 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: yolo (auto-approve all), plan (approve safe operations), or safe (confirm every action). Permission cycles on click with color-coded borders.

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.7.0+
• Desktop only (macOS, Linux, Windows)

Installation

Obsidian Community Plugins

1. Open Obsidian Settings → Community plugins → Browse
2. Search for "Copsilot" and install
3. Enable the plugin in Community plugins settings

Manual

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

   /path/to/vault/.obsidian/plugins/copsilot/
   

3. Copy the downloaded files into the copsilot folder
4. Enable the plugin in Obsidian: Settings → Community plugins → Enable "Copsilot"

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/copsilot.git
   cd copsilot
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Enable the plugin in Obsidian:
   • Settings → Community plugins → Enable "Copsilot"

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: Copsilot settings and session data are stored in Obsidian's plugin data (data.json within .obsidian/plugins/copsilot/). Synced notes are created in your configured folder (default: opencode-sync/).
• No telemetry: Copsilot 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

• Ensure the target folder exists in your vault
• 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
│   ├── copsilotView.ts          # Obsidian ItemView: DOM composition, input, drag/drop, keybindings
│   ├── copsilotViewController.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

---

Copsilot 中文说明

English | 中文

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

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

为什么做 Copsilot

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

功能特性

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

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

输出自动保存为笔记：AI 生成的内容通过同步引擎直接保存到本地 Vault，无需手动复制粘贴。

模型与模式切换：在界面中直接切换 AI 模型和 Agent 模式（build / plan / docs）。

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

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

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

权限模式：选择控制级别：yolo（全部自动批准）/ plan（批准安全操作）/ safe（逐一确认）。

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

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

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

系统要求

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

安装方式

Obsidian 官方插件市场

1. 打开 Obsidian 设置 → 第三方插件 → 社区插件市场
2. 搜索 "Copsilot" 并安装
3. 在第三方插件设置中启用插件

手动安装

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

   /path/to/vault/.obsidian/plugins/copsilot/
   

3. 将下载的文件复制到 copsilot 文件夹
4. 在 Obsidian 中启用插件：设置 → 第三方插件 → 启用 "Copsilot"

从源码安装（开发）

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

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

2. 安装依赖并构建：

   npm install
   npm run build
   

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

配置说明

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

键盘快捷键

隐私与数据

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

故障排除

找不到 OpenCode CLI

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

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

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

会话重启后丢失

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

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

同步规则没有创建笔记

• 确保目标文件夹在 Vault 中存在
• 检查设置中该同步规则是否已启用
• 确认工具名称与 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/                        # 侧边栏对话视图
│   ├── copsilotView.ts          # Obsidian ItemView：DOM 组合、输入、拖拽、快捷键
│   ├── copsilotViewController.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 协议