Pidian

Pi Coding Agent in Obsidian

English | 日本語

A plugin that lets you chat with an AI in the Obsidian sidebar to ask about or edit the open note, search notes, and search the web.

It includes the AI harness Pi Coding Agent, so you get a strong agent experience without extra tools. It supports OpenAI, Anthropic, xAI, OpenRouter, and many other providers.

What it can do

The AI agent decides on its own when to read, write, and search notes.

• Ask about the note or image you currently have open
• Find notes in the vault
• Read PNG, JPEG, and WebP images from the vault
• Edit notes
• Restrict edits, web search, and similar actions with permissions

Install

Install from the Obsidian Community Plugins.

To build from source, see CONTRIBUTING.md.

Quick start

When you enable the plugin, the Pidian sidebar opens on the right. After you close it, reopen it from the left ribbon, or from the command palette with Open Pidian.

1. Go to Settings → Pidian → API credentials. Sign in under Subscriptions for ChatGPT Plus/Pro (Codex), or enter an API key for the service you use
2. Choose a provider and model under General, or at the bottom of the sidebar
3. With a note or other vault file open, type a message in the sidebar. Paste a clipboard image to attach it; Vision-compatible models can see it

If you leave the API key blank, Pidian uses environment variables. ChatGPT Plus or Pro can sign in from Subscriptions instead of an API key.

Start a new conversation with New chat in the sidebar, or with the New Pidian chat command.

Permissions

To prevent accidental changes, everything except read is restricted by default. Change this under Settings → Pidian → Permissions.

Action	Default	What it covers
Read	Always allow	Read notes and PNG/JPEG/WebP images, search the vault, list folders, open and switch tabs
Edit	Ask every time	Change an existing note. The target file and a diff are shown before running
Create	Deny	Create a new note
Delete	Deny	Trash a note according to Obsidian's trash settings
Web search	Ask every time	Search the web and fetch pages

When set to Ask every time, you are prompted to allow or deny before the action runs. Denying stops only that action. The conversation continues.

To let the agent create notes, delete notes, or search the web, change only the permissions you need to Ask every time or Always allow.

Edits go through Obsidian, so you can undo them with Obsidian's standard Undo.

Context

When you send a message, Pidian includes the path of the active file. When that file is open in a Markdown editor, it also includes the cursor position or selection. Canvas, Excalidraw, and PNG, JPEG, or WebP images include the path only. The agent reads an image with read_image when the current model supports vision.

You can also paste a PNG, JPEG, or WebP image from the clipboard into the chat input. Pidian stores it in the conversation file and shows a thumbnail. Restored sessions keep the thumbnail in the chat UI but do not send the image bytes to the model again. If the selected model does not support vision, Send is disabled while an image is attached.

Saving conversations

Conversations are saved in a plugin folder in the vault (default: pidian/sessions/). You can change the location under Settings → Pidian → General → Plugin folder.

Under Settings → Pidian → Session, you can automatically delete conversations on startup: older than the retention period, over a retained-count limit, or both.

Extra instructions (optional)

If you add pidian/AGENTS.md (when the plugin folder is the default) and write instructions for the AI's tone and behavior, you can customize how it works. The plugin works without this file.

# Instructions

- Reply in English
- Keep the note's writing style
- Always check the content before editing

API keys

API keys are stored in Obsidian plugin data.

Priority, from highest to lowest:

1. Pidian settings API key
2. Subscription sign-in (ChatGPT Plus/Pro Codex)
3. Environment variables

Example environment variables:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• GEMINI_API_KEY
• OPENROUTER_API_KEY

For Chat Completions-compatible endpoints, add Name / Base URL / Model ID / API key under Settings → Pidian → API credentials → Custom OpenAI Compatible. Turn on Vision for a model if it can receive images. It is off by default.

Limitations

• Desktop only (no mobile support)
• Does not operate on .obsidian/ or conversation files
• Pi Coding Agent extensions cannot be used

For developers

Build, architecture, testing, and release steps are in CONTRIBUTING.md.

Third-party assets

NOTICE.md

License

MIT