README file from
Github▶️ One errand, start to finish
You have a clipped article open. Saved months ago, never acted on. You type into the side panel:
Based on this note, recommend a beginner's hardware list with buying advice.
Current UI captured in an isolated Obsidian demo vault. The conversation is scripted; the plugin's read, write and edit tools actually ran.
It read the note. Wrote a new one beside it — hardware table, buying
advice, beginner steps. Then went back to the original and added a
[[wikilink]] pointing at the new note, so the graph knows they belong
together.
Two files touched: a hardware checklist saved, a backlink added (+4 −0 on the original). Thinking and tool calls share folded groups; open one to see each step. The reply names the notes it changed.
You never opened a file. You read the receipt and got on with your day.
That is the whole idea. Piem has hands — two dozen vault tools — and it uses them.
☕ If it just saved you an afternoon
Piem is free, MIT licensed, and staying that way. It is one person's evenings-and-weekends project. If it just did an hour of work you had been dreading, coffee is a fair trade.
🧰 What else it has in hand
| Two dozen vault tools | read, search, write, edit, move, trash, walk links, rewrite frontmatter, sweep tasks, drive the editor — see them all |
| Subagents, in parallel | hand off a self-contained task; isolated transcript, capped at three levels by construction, not by a check — how they work |
| MCP servers | remote tools merge into the agent's own tool set, name-spaced so a transcript never lies about where a tool came from — connect one |
| Skills | reusable instructions from bundled, from your vault, or from the ~/.pi folders you already use with pi. Type / — write one |
| Context that follows you | the note you have open — path and body — rides along with every turn, and the conversation compacts itself when the window fills |
| Proactive perception | while you write, a background scout reads the note you have open and finds the missing frontmatter, the broken link, the external reference whose takeaway was never recorded — and stages each as a tap-to-run suggestion. It only suggests; it never edits on its own |
| Suggestions in context | an empty panel opens with first moves the model shapes to the note you have open; after a reply, a fresh row of follow-ups arrives — the obvious next step first, a deeper one behind it — beside copy, insert at cursor, append to the note, or ask again in place |
| Your endpoint, your key | any OpenAI-compatible or Anthropic-messages base URL, sixteen presets to start from, capabilities auto-filled — configure it |
| Images | paste or drop them into the composer and they ride along |
| English & 简体中文 | follows Obsidian's own language, with an override when you want otherwise |
⏱️ Up and running in five minutes
1. Install it. Easiest path is BRAT:
install BRAT from Obsidian's community plugins, then Add beta plugin →
YoungSx/piem. It handles updates for you.
Prefer to do it by hand? Grab main.js, manifest.json, and styles.css from
the latest release, drop them
into <vault>/.obsidian/plugins/piem/, reload Obsidian, and enable Piem
under Settings → Community plugins.
2. Give it a brain. Open Settings → Piem → Models, add a provider and an API key. DeepSeek is the default suggestion; anything OpenAI-compatible or Anthropic-messages works, and the Test button probes your endpoint over the same transport your chats will use.
3. Ask it something. Command palette → Piem: Open chat. Then say the thing you have been avoiding. Ctrl/⌘+Enter sends — or switch it to plain Enter in General.
Building from source instead? CONTRIBUTING.md has the five commands.
📱 Your phone counts as a real computer
Piem ships with isDesktopOnly: false and means it. Tools, subagents, skills,
images — all of it works on a phone. So does streaming, once you turn it on.
That commitment costs something, and it is worth knowing what.
MCP servers are remote only. A stdio transport would spawn child processes and a phone cannot. A capability that cannot exist on mobile gets refused for everyone rather than shipped as a desktop-only surprise.
Token-by-token streaming is off by default. Obsidian's requestUrl is the
only request path free of CORS on every platform, and it has no incremental
read at all — a reply lands whole, when it finishes. Real streaming means the
browser's own fetch, which most endpoints do accept; it is one setting away
(Models → Network → Network transport). It stays the non-default because
whether it works is the endpoint's call rather than ours, and a locally hosted
model usually has to be told to allow it.
🔓 Before you install: it edits without asking
There is no confirmation step before write or edit. No dialog, no diff
to approve. You ask, and your notes change.
That is deliberate, and it is the deal: an agent that asks permission twelve times is an agent you stop using. What it asks of you in return:
- point it at a vault you are willing to have changed, and to have sent to your model provider — a search that touches a file sends that file;
- read the transcript afterwards. Every change came from a tool call, and every tool call is right there, in the open;
- keep the vault in version control, or lean on Obsidian's file recovery.
trash_notegoes through Obsidian's trash, so deletions come back the ordinary way.
Your API keys are sealed with your OS keychain on desktop, and stored in plaintext on mobile — because there is nothing to seal with there, and saying so is better than implying otherwise. Release builds carry signed provenance, so the bytes you downloaded can be traced back to this repo.
Error reports and performance data go to Piem's maintainers by default; you can turn sharing off in Extensions. Content capture is off, but error messages may include note text. Security and privacy explains what is sent.
📚 Go deeper
| The agent's tools | Every tool, what it cannot do, and how subagents work |
| Extending Piem | Skills, prompt templates, MCP servers |
| Settings | Providers and models, chat behavior, commands, where sessions live |
| Security and privacy | What leaves your vault, where keys live, the capabilities Obsidian's review flags |
Contributing? CONTRIBUTING.md for the workflow, AGENTS.md for the conventions.
🙏 Standing on shoulders
Piem runs on @earendil-works/pi-agent-core,
the pi agent runtime — which is why the skills you already wrote for pi work
here unchanged.
It grew from lhr0909/pi-obsidian.
Thank you for that starting point.
MIT licensed. Third-party notices in THIRD_PARTY_NOTICES.md.