English ｜ 中文说明

Run the pi coding agent in an Obsidian sidebar: chat next to your notes, and send the current note, the current selection, or a pasted image to pi with one click. pi reads and writes your vault directly.

Author 3zh ｜ License MIT ｜ Repo https://github.com/zzzzzllllllaaaa/obsidian-pi-panel

Install

From the community directory (recommended)

1. Obsidian → Settings → Community plugins → Browse
2. Search for Pi Panel → Install → Enable

Manually, from a GitHub release

1. Download main.js, manifest.json and styles.css from the latest release
2. Copy them into <your vault>/.obsidian/plugins/pi-panel/
3. Restart Obsidian → Settings → Community plugins → enable Pi Panel

Requirements

• Desktop Obsidian 1.7.2+. On mobile, run pi on your computer and use remote mode below.
• The pi CLI installed and working (pi --help in a terminal).
• If Obsidian cannot find pi — GUI apps often miss npm's global bin directory — set the absolute path in the plugin settings, for example %APPDATA%\npm\pi.cmd.

What you get

• Sidebar chat panel — ribbon icon or the Pi Panel: Open panel command. Streaming replies with thinking blocks (collapsible) and tool-call cards showing name, arguments, duration and output; failed calls expand automatically.
• One-click references — Note sends the note you have open (very long notes are sent as @path only), Selection sends the selected paragraphs with file and line numbers. Images can be pasted or dragged into the panel; other dropped files are inserted as @path.
• Text you can select — drag-select and copy from the chat like in a browser.
• Usage chip — the header shows context and token usage for the session (ctx 30% · 59k/200k · 4.9M tok); click it for input / output / cache numbers, tool-call count and cost when pi reports one.
• Extension prompts stay in the panel — when pi asks for a confirm / select / input, you answer in the panel, so the agent never hangs waiting on a terminal.
• History — browse ~/.pi/agent/sessions/, replay a session, rename it, or start fresh.
• Model switching — click the model name in the panel header to switch instantly (no process restart); edit models.json from the settings page.
• Tool allow-list you control — whatever you pass to --tools is what pi gets. Nothing is enabled behind your back.
• Keeping pi's working directory separate from the vault — point pi at a project folder that has its own AGENTS.md, while your notes stay in the vault.
• AI operation log — an optional separate panel that records which notes were created / modified / deleted / renamed while the plugin runs, with time, path and a short preview. Click a row to open the note.

Settings

Tool permissions

pi's built-in tools are read, bash, edit, write, grep, find, ls. The plugin turns your checkboxes into --tools <list> — a session without bash has no shell in pi, so it cannot change directories or run commands.

Three presets:

• Empty = --tools is not passed at all, so pi keeps all of its default tools.
• If the allow-list has no bash, the panel says so in the chat and marks no bash in the debug log.

Context and rules ("why is my AGENTS.md ignored?")

At startup pi looks for AGENTS.md / CLAUDE.md in ~/.pi/agent/, then in every parent directory of its working directory, then in the working directory itself.

The panel's working directory defaults to your vault root, so a rules file that lives in some project folder is not read. Two fixes:

1. Extra system prompt file → point it at that file (recommended: note paths stay untouched).
2. Working directory → point it at the project folder (cwd changes, so pi's relative paths and @ search change with it).

Changing either setting restarts the pi process in the panel; the next message uses it. Remember that a rules file telling pi to run shell commands needs bash in the allow-list.

History and sessions

The History button in the header lists sessions found in ~/.pi/agent/sessions/<cwd slug>/*.jsonl:

• The list has a search box: filters by name, first-message summary, session id, cwd or file path.
• Each row shows time, a summary of the first user message, message count and session id; sessions from another cwd are labelled.
• Clicking a row restarts pi with --session <file> and replays that session's history.
• Header buttons: New session and Continue last (--continue).
• If the current cwd has no session files, recently used working directories are listed instead (with their cwd shown).
• Rename from the ✏️ button on any row; empty input clears the name.

Model management

Click the model line in the panel header (for example deepseek-v4-flash · persist · 3 msgs) to open the model picker:

• The list comes from pi's get_available_models (built-in plus your models.json), grouped by provider.
• ☆ pins a model to a "Favorites" section.
• Picking a row switches the running process instantly (RPC set_model) and remembers the choice for the next start.
• If pi is not running, the picker starts it to fetch the full list — no need to type provider/id by hand.
• Manage models… edits ~/.pi/agent/models.json: add or edit providers (name, api type, baseUrl, apiKey, compat.supportsDeveloperRole) and models (id, display name, api, contextWindow, maxTokens, reasoning, image input, cost).

Every save is validated locally first — invalid input is rejected, and the previous file is backed up as models.json.bak-<timestamp>. This matters because pi's model registry drops the whole file if any single entry is invalid, and the only symptom is a shorter model list.

Remote mode

Mobile Obsidian has no way to run pi locally, so the plugin can talk to pi on your computer over a WebSocket:

mobile Obsidian ──ws──> bridge on your computer ──spawn──> pi --mode rpc

1. Run a WebSocket bridge on the computer that exposes pi's RPC mode (endpoints: WS /rpc, GET /sessions?cwd=, POST /sessions/rename, GET/PUT /models, GET /health).
2. In the plugin settings: connection mode = Remote, bridge address = ws://<computer-ip>:8770, bridge token = the token that bridge was started with.
3. Away from home, reach the same bridge through a VPN such as Tailscale (ws://100.x.x.x:8770), or expose it behind your own TLS relay and use wss://.

Limits:

• The models.json editor is unavailable in remote mode (the file lives on the computer — edit it there).
• Give remote sessions a narrow allow-list (read,grep,find,ls, add write,edit if you need edits). bash means the phone can drive the whole computer.
• Always keep a token on the bridge and never expose it on a public port.

AI operation log

A separate view (Pi Panel: Open AI operation log, or the list icon in the ribbon) that lists vault changes seen while the plugin is running:

• Types: create / modify / delete / rename, with time, vault path and the first ~160 characters of the file when there is content.
• Only folders listed in Folders to watch are recorded; nothing is read from folders you did not list. Put / (or *) there to record the whole vault — .obsidian and the trash are always skipped.
• Click a row to open that note. Refresh re-renders, Clear empties the list (the notes themselves are never touched).
• The last 300 entries are kept in this plugin's data.json.

Note that it records what changed in the watched folders, not which process changed it: an edit you make by hand is listed too. Use it as an activity trail, not as an audit log.

Debug log

Three entry points: the bug button in the panel header, the Pi Panel: View debug log command, or "Open log" in the settings.

The dialog shows environment details (plugin version, Obsidian version, platform, pi path, working directory, vault root, the actual spawn command line, session mode, tool allow-list, default model, status, log path) plus the raw SEND / RECV JSONL, STDERR, ERROR entries with stack traces, and user actions. Copy all puts environment and log on the clipboard.

The log is also written to <vault>/.obsidian/plugins/pi-panel/pi-panel-debug.log (rotated to .1 past 5 MB). Streaming text deltas are omitted so the file stays readable; other events are stored verbatim, truncated at 6000 characters per line. When reporting a problem, paste Copy all — it usually identifies the cause immediately.

Privacy and data

• No telemetry, no analytics. The plugin collects and uploads nothing.
• Network: offline by default. A WebSocket is opened only if you switch connection mode to Remote, and only to the bridge address you specify.
• Files outside the vault (desktop): running pi locally inevitably touches paths outside your vault:
  • ~/.pi/agent/ — pi's own configuration and session records (models.json, sessions/*.jsonl), read and written by the History and model manager features;
  • the working directory you configure (may be empty = vault root), used as pi's cwd so it can read an AGENTS.md or project files there;
  • the pi executable path you configure (for example %APPDATA%\npm\pi.cmd);
  • the bridge token, stored in the plugin's data.json, when remote mode is enabled.
• AI operation log (optional): when enabled it stores up to 300 entries — relative path, time, change type and the first ~160 characters of the file — in the plugin's data.json. Only folders you list under Folders to watch are inspected, and nothing is uploaded.
• Subprocess: the plugin spawns pi on your machine (child_process, desktop only and loaded lazily — never on mobile). Closing the panel stops that process.
• Tool permissions: you decide the allow-list. Granting bash grants command execution; judge accordingly.

License

MIT — use it however you like, commercially included.

Bug reports and ideas: GitHub Issues. This is a personal project and I make no promise about a maintenance schedule.

中文说明

在 Obsidian 侧边栏里跑 pi coding agent：边看笔记边提问，一键把当前笔记、选中段落或粘贴的图片丢给 pi，pi 直接读写你的库。

安装

从社区目录装（推荐）

1. Obsidian → 设置 → 第三方插件 → 浏览
2. 搜索 Pi Panel → 安装 → 启用

手动装（从 GitHub Release）

1. 到 最新 Release 下载 main.js、manifest.json、styles.css
2. 放进 <你的库>/.obsidian/plugins/pi-panel/
3. 重启 Obsidian → 设置 → 第三方插件 → 启用 Pi Panel

前置条件

• 桌面端 Obsidian 1.7.2+。手机上请把 pi 跑在电脑里，用下面「远程模式」。
• 本机装好 pi CLI（终端 pi --help 能用）。
• 如果 Obsidian 找不到 pi（GUI 进程的 PATH 常常没有 npm 全局 bin），在设置里填绝对路径，例如 %APPDATA%\npm\pi.cmd。

功能

• 侧边栏聊天面板 —— ribbon 图标或命令 Pi 面板：打开面板。流式输出，thinking 可折叠，工具调用卡片显示名称、参数、耗时、输出，出错自动展开。
• 一键引用 —— 笔记 按钮给当前打开的笔记（超长只给 @路径），选区 按钮给选中段落（带文件:行号）。图片可粘贴，也可直接把文件拖进面板；拖进来的其它文件按 @路径 插入。
• 聊天文字能划选 —— 像浏览器一样鼠标划选 + 复制。
• 用量 chip —— 头部显示本会话的上下文与 token 用量（ctx 30% · 59k/200k · 4.9M tok），点开看 input / output / cache 明细、工具调用次数，pi 报了 cost 才有金额。
• 扩展 UI 弹窗在面板内应答 —— pi 要 confirm / select / input 时不用切终端，agent 不会挂住。
• 历史会话 —— 扫 ~/.pi/agent/sessions/，列表顶部有搜索框（按名字 / 首条摘要 / 会话 id / 工作目录 / 文件路径过滤），可回放、可重命名、可开新会话。
• 模型即时切换 —— 面板头点模型名即换（不重启进程）；设置页可直接改 models.json。
• 工具白名单自己定 —— --tools 传什么就是什么，不会背着你开权限。
• 工作目录与笔记目录分离 —— 可以把 pi 指向带自己 AGENTS.md 的项目目录，笔记仍在库里。
• AI 操作记录 —— 可选独立面板，记录插件运行期间被新建 / 修改 / 删除 / 改名的笔记（时间、路径、前 160 字预览），点一行直接打开。

设置项

工具权限

pi 内置工具：read bash edit write grep find ls。面板把勾选拼成 --tools <列表> —— 没勾 bash 的会话里 pi 就没有 shell，连列目录、跑命令都做不到。

三个预设：

• 留空 = 完全不传 --tools，即 pi 默认的全部工具。
• 白名单不含 bash 时，面板会在聊天里提示，调试日志里也会标注「无 bash」。

上下文 / 规则为什么不生效

pi 启动时按这个顺序找 AGENTS.md / CLAUDE.md：~/.pi/agent/ → cwd 的各级父目录 → cwd 本身。

面板默认 cwd 是 vault 根，所以放在某个项目目录里的规则文件不会被读到。两种修法：

1. 附加系统提示文件 → 指向那个文件（推荐，笔记路径不受影响）。
2. 工作目录 → 指向项目目录（cwd 变了，pi 的相对路径与 @ 搜索也跟着变）。

改完设置会自动重启面板里的 pi 进程，下一条消息生效。另外：规则里若有跑命令的步骤，记得把 bash 加进白名单。

历史会话

头部 历史 按钮列出 ~/.pi/agent/sessions/<cwd slug>/*.jsonl：

• 每行显示时间、首条用户消息摘要、消息数、session id；其它 cwd 的会话会标注。
• 点一行 → 以 --session <文件> 重启 pi 并回放该会话历史。
• 头部按钮：新会话 / 继续上次（--continue）。
• 当前 cwd 没有会话文件时，会回退列出最近活跃的其它工作目录（列表里标出 cwd）。
• 每行 hover 出现 ✏️ 可重命名；留空 = 清除名字。

模型管理

面板头那行模型名（如 deepseek-v4-flash · persist · 3 msgs）点一下打开模型选择器：

• 列表来自 pi 的 get_available_models（内置 + models.json 自定义），按 provider 分组。
• ☆ 收藏 → 下次置顶显示。
• 点一行即时切换（RPC set_model），并记为下次启动的默认值。
• pi 没启动时选择器会先把它拉起来再取完整列表，不用手打 provider/id。
• 「管理模型…」可增删改 ~/.pi/agent/models.json：供应商（名字 / api 类型 / baseUrl / apiKey / compat.supportsDeveloperRole）与模型（id、显示名、api、contextWindow、maxTokens、reasoning、图片输入、cost）。

保存前会本地校验：校验不过就拒绝写盘，并把原文件备份成 models.json.bak-<时间戳>。这条很关键 —— pi 的模型注册表遇到任何一个不合法条目就会丢弃整个文件，界面不报错，只表现为模型列表变少。

远程模式

手机装不了 pi，所以由插件用 WebSocket 连电脑上的桥：

手机 Obsidian ──ws──> 电脑上的桥 ──spawn──> pi --mode rpc

1. 在电脑上跑一个暴露 pi RPC 模式的 WebSocket 桥（端点：WS /rpc、GET /sessions?cwd=、POST /sessions/rename、GET/PUT /models、GET /health）。
2. 插件设置里：连接模式 = 远程，桥地址 = ws://<电脑IP>:8770，桥 token = 启动桥时用的那个。
3. 出门在外：用 Tailscale 之类的虚拟局域网连同一地址（ws://100.x.x.x:8770），或者把桥放到自己的 TLS 中继后面用 wss://。

限制：

• 远程模式下 models.json 管理器不可用（文件在电脑上，请在电脑上改）。
• 远程会话建议用窄白名单（read,grep,find,ls，要改笔记再加 write,edit）。给了 bash = 手机能操作你整台电脑。
• 桥必须带 token，不要暴露公网端口。

AI 操作记录

独立面板（命令 Pi 面板：打开 AI 操作记录面板，或左侧 ribbon 的列表图标），列出插件运行期间监听到的库内变更：

• 类型：新建 / 修改 / 删除 / 改名，带时间、vault 路径，以及有内容时该文件前 160 字预览。
• 只记录监听目录里列出的文件夹，没列出的目录一个字都不读；填 /（或 *）= 整个库，.obsidian 和回收站永远跳过。
• 点一行打开对应笔记；刷新 重画，清空 只清列表（不动笔记）。
• 只保留最近 300 条，存在本插件的 data.json。

它记的是「监听目录里变了什么」，不是「谁改的」：你自己手改的也会被列出来。当活动轨迹看，别当审计日志。

调试日志

三个入口：面板头 🐞 按钮 / 命令 Pi 面板：查看调试日志 / 设置页「打开日志」。

弹窗里有环境信息（插件版本、Obsidian 版本、平台、pi 路径、工作目录、vault 根、实际 spawn 的命令行、会话模式、工具白名单、默认模型、状态、日志路径），以及原始的 SEND / RECV JSONL、STDERR、ERROR（含堆栈）、用户操作。复制全部 会把环境信息与日志一起放进剪贴板。

日志同时落盘到 <vault>/.obsidian/plugins/pi-panel/pi-panel-debug.log（超 5MB 轮转成 .1）。流式文本增量不记录，避免刷爆；其他事件记原文，单行截断 6000 字符。报问题时把「复制全部」的内容贴出来即可，一般一眼能定位。

权限与数据

• 无遥测、无埋点：插件不收集也不上传任何数据。
• 网络：默认不联网。只有你主动把连接模式改成 远程 时，才会用 WebSocket 连你自己指定的桥地址。
• 访问 vault 之外的文件（桌面端）：本机跑 pi 难免碰库外路径，具体是：
  • ~/.pi/agent/ —— pi 自己的配置与会话记录（models.json、sessions/*.jsonl），「历史会话」与「模型管理」直接读写这里；
  • 你设置的工作目录（可留空 = vault 根）—— 作为 pi 的 cwd，因为它要从那里读 AGENTS.md / 项目文件；
  • 你设置的 pi 可执行文件路径（例如 %APPDATA%\npm\pi.cmd）；
  • 开远程模式时读桥的 token（存在插件 data.json 里）。
• AI 操作记录（可选）：开启后最多存 300 条到本插件 data.json —— 相对路径、时间、变更类型、文件前 160 字。只读你填在监听目录里的文件夹，不上传任何内容。
• 子进程：插件在本机 spawn pi（child_process，仅桌面端且惰性加载，移动端不加载）。关面板会杀掉这个进程。
• 工具权限：白名单由你决定；给了 bash 就是给了命令执行权，请自行评估。

授权

MIT —— 随便用，商用也行。

意见与 bug 走 GitHub Issues。本插件为个人项目，不承诺维护节奏。