Obsypi

Obsypi is a desktop-first Obsidian sidebar copilot that combines a native right-sidebar chat UI with a local plugin-owned vault tool layer and an internal pi helper runtime.

The current MVP targets:

• a native Obsidian ItemView in the right sidebar
• OpenCode Go as the first supported model provider
• plugin-owned vault reads, writes, moves, renames, and trash actions
• guarded .obsypi/ session storage and mutation journaling

What It Does Today

• Opens a dedicated Obsypi sidebar from the ribbon or open-panel command
• Stores provider settings in plugin data, not in your vault
• Streams assistant responses into the sidebar timeline
• Routes tool calls back through Obsidian APIs for vault-safe operations
• Persists internal state under .obsypi/ for transcripts, sessions, and audit logs

Status

This repository contains an active MVP implementation and a research/planning corpus for the next iterations.

Relevant docs:

• docs/README.md for the research hub
• docs/DECISIONS.md for accepted architecture defaults
• docs/SOURCE_INDEX.md for pinned references
• CONTRIBUTING.md for contributor workflow notes

Development

Requirements:

• Node.js 20+
• npm
• Obsidian desktop 1.7.2+

Install and run:

npm install
npm run dev

Build and test:

npm run build
npm test
npm run lint

Local Setup

For local development, symlink the repo into a dev vault at:

<vault>/.obsidian/plugins/obsypi

That lets npm run dev rebuild directly into the live plugin directory while Obsidian is open.

Manual Testing

1. Run npm run dev.
2. Open your dev vault in Obsidian.
3. Enable obsypi in Settings → Community plugins.
4. Open the sidebar with the ribbon icon or Open Obsypi sidebar.
5. Configure the OpenCode Go API key and model in the Obsypi settings tab.
6. Send a prompt and verify sidebar streaming, tool summaries, and .obsypi/ persistence.

Repository Structure

src/
  main.ts              Plugin lifecycle and commands
  settings.ts          Persisted plugin settings and settings UI
  runtime/             Helper process bridge and controller
  ui/                  Sidebar view
  vault/               Guarded vault tools and path normalization
  persistence/         .obsypi session and journal storage
helper/
  src/                 Internal Node helper runtime
shared/
  protocol.ts          Typed JSONL protocol between plugin and helper
docs/
  research/            Architecture and MVP research notes

Privacy And Safety

• Obsypi is designed to keep vault mutations inside the plugin through Obsidian APIs.
• API keys are stored in plugin data only.
• Reserved roots such as .obsidian/, .trash/, and .obsypi/ are blocked from general tool access.
• Mutation attempts and successes are journaled under .obsypi/.

Plugin Release Notes

Obsidian community plugin releases need these top-level assets attached to the GitHub release:

• manifest.json
• main.js
• styles.css

The version in manifest.json must match the Git tag exactly, without a leading v.

License

Licensed under the 0BSD license. See LICENSE.