Obssistant

Obssistant is a FOSS Obsidian plugin that brings a natural agent interface into your vault. It lets you chat with the active note and a small set of related notes, then insert useful responses back into your writing.

This repository is an early foundation for the plugin: useful enough to try, small enough to understand, and designed for community iteration.

Features

• Side-panel assistant view inside Obsidian.
• Local ACP agent mode for Claude Agent, Codex, or a custom command.
• Bring-your-own OpenAI-compatible chat completions endpoint.
• Optional active-note context.
• Lightweight keyword matching for related vault notes.
• Local settings only; no telemetry.
• Insert assistant responses into the active note.

Install for development

npm install
npm run dev

Then copy or symlink this folder into your test vault:

mkdir -p "/path/to/Vault/.obsidian/plugins"
ln -s "$PWD" "/path/to/Vault/.obsidian/plugins/obssistant"

Enable community plugins in Obsidian, reload the app, and enable Obssistant.

Build

npm run build

The release assets for Obsidian are:

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

Configuration

Open Obsidian settings, then configure Obssistant:

• Backend: choose local ACP agent or OpenAI-compatible endpoint.
• Model: choose Opus or GPT; Obssistant automatically uses the matching local agent.
• Tool updates: choose compact, hidden, or inline rendering for agent tool activity.
• Command and arguments: defaults use npx to launch the Zed-maintained ACP adapters.
• API endpoint: an OpenAI-compatible /chat/completions endpoint.
• API key: optional for local endpoints, required for many hosted providers.
• Model: the model name expected by your endpoint.
• Context controls: active note, related note count, and per-note character cap.

API keys are stored in this vault's plugin data. Treat vault backups and synced plugin data accordingly.

Local ACP agents

The default local agent commands are:

npx --yes @agentclientprotocol/claude-agent-acp@latest
npx --yes @zed-industries/codex-acp@latest

Authenticate Claude Code or Codex in your normal terminal first. Obssistant starts the selected ACP adapter with the vault root as its working directory, creates an ACP session, and sends prompts to that local agent.

Local ACP mode is desktop-only because it launches subprocesses.

On macOS, Obsidian may not inherit the same PATH as your terminal. Obssistant therefore launches local ACP agents through /bin/zsh -lc by default so tools such as npx, node, claude, and codex can be found through your normal shell setup.

In the chat composer, press Enter to send. Press Shift+Enter to insert a new line.

Privacy

Obssistant does not include telemetry, analytics, or a hosted backend. When you send a message, the plugin sends the conversation plus enabled vault context to the endpoint you configure.

Before using Obssistant with sensitive vaults, choose an endpoint whose privacy, retention, and security practices you trust.

Roadmap

• Streaming responses.
• Better semantic retrieval with a local index option.
• Conversation persistence per vault.
• Tool-style actions with explicit user approval.
• Source citations and note backlinks in responses.
• Provider presets for local and hosted models.

Community release note

Obsidian's community plugin guidelines currently require plugin IDs to avoid the word obsidian, and their naming guidance discourages names that include Obsidian or close variations. Obssistant avoids the literal restricted ID, but the name may still need review before community-directory submission.

License

AGPL-3.0-or-later. See LICENSE.