Obsidian Stats logoObsidian Stats

Vault Loom

by yangzuo0621
5
4
3
2
1
Score: 50/100
Install Code

Description

AI assistant for context-aware chat, vault retrieval, and confirmed note actions in Obsidian.

Reviews

No reviews yet.

Stats

0
stars
73
downloads
0
forks
102
days
102
days
102
days
34
total PRs
0
open PRs
0
closed PRs
34
merged PRs
0
total issues
0
open issues
0
closed issues
38
commits

Latest Version

1.0.2
3 months ago

Changelog

Patch release for Obsidian Community review.

Changes:

  • Renamed the settings section heading from the plugin name to Provider to satisfy the Community source-code review rule.

Release assets for Obsidian installation are attached below: main.js, manifest.json, and styles.css.

See all version on GitHub

README file from

Github

Vault Loom

简体中文

Weave your vault into useful AI context. Vault Loom combines streaming chat, note-aware retrieval, editing commands, and a confirmation-gated agent mode for Obsidian.

Features

  • Stream assistant responses and stop an active generation.
  • Use the current selection or active note as structured context.
  • Find relevant Markdown notes with keyword search.
  • Optionally index Markdown chunks for embedding-based semantic retrieval.
  • Preview the context attached to the latest request.
  • Create, switch, restore, and delete chat sessions.
  • Explain or rewrite a selection and summarize the current note from the command palette.
  • Run a bounded Agent mode with visible tool activity and per-operation confirmation for note writes.
  • Connect to configurable OpenAI-compatible chat and embedding endpoints.

Requirements and compatibility

  • Desktop Obsidian 1.12.7 or later.
  • An OpenAI-compatible endpoint and any credentials required by that endpoint.

The first public release is desktop-only. Mobile support may be enabled after the complete workflow has been verified on Obsidian mobile.

An endpoint may support chat completions without supporting streaming, tool calls, or embeddings. Chat mode only requires compatible chat completions; Agent mode requires tool-calling support, and semantic retrieval requires an embeddings endpoint.

Installation

Community Plugins

Vault Loom is available in the Obsidian Community Plugins directory. Install it from Settings → Community plugins inside Obsidian.

Manual installation from source

  1. Install Node.js and clone this repository.

  2. From the repository root, run:

    npm ci
npm run build

  3. Create a plugin folder inside your vault:

    <vault>/.obsidian/plugins/vault-loom/

  4. Copy main.js, manifest.json, and styles.css into that folder.

  5. Reload Obsidian, open Settings → Community plugins, and enable Vault Loom.

For a development vault, set OBSIDIAN_PLUGINS_DIR in .env.local and run npm run deploy:test. You can also pass the destination directly:

npm run deploy:test -- "<vault>/.obsidian/plugins"

Configuration

Open Settings → Vault Loom and configure:

Setting Purpose Default
API key Credential stored in Obsidian plugin data Empty
Base URL OpenAI-compatible API base URL https://api.openai.com/v1
Model Chat completions model name gpt-4o-mini
Embedding model Model used for semantic retrieval text-embedding-3-small
Temperature Response randomness from 0 to 2 0.7
Context token budget Estimated token budget for attached context 4000
Include selection Prefer the active editor selection as context On
Include current file Use the active note when there is no selection On
Include vault search Attach keyword-matched note snippets On
Include embedding retrieval Index and retrieve semantically related chunks Off

Use Test provider from the command palette to check the chat configuration.

Usage

Chat

Open the sidebar with the ribbon bot icon or Open chat from the command palette. Enter a prompt and select Send. Responses stream into the active session, and Stop cancels the current request.

The context preview shows which selection, current note, keyword matches, or semantic matches were attached. Context is estimated and trimmed to the configured budget before prompt composition.

Chat sessions are stored in Obsidian plugin data and restored after the plugin reloads. Creating, switching, and deleting sessions does not modify Markdown notes.

Editing commands

Command Result
Explain selection Inserts an explanation for the selected text
Rewrite selection Replaces the selected text with a rewrite
Summarize current note Inserts a summary into the active editor

Running one of these commands is the explicit action that authorizes its editor change. If the request fails, the command does not write generated text.

Agent mode

Select Agent in the Vault Loom sidebar to allow the model to request registered tools. Agent execution is sequential and bounded, and tool activity remains visible in the conversation.

Tool Access Behavior
search_vault Read Searches Markdown note names and content
read_note Read Reads one vault-relative Markdown note
create_note Write Creates a new note without overwriting an existing one
append_to_note Write Appends Markdown to an existing note
replace_selection Write Replaces the current non-empty editor selection

Every write tool displays a preview and requires approval before it runs. If the active note or selection changes while a replacement is awaiting approval, the replacement is rejected.

Privacy and data handling

This plugin connects directly from Obsidian to the API base URL you configure. Review the privacy and retention terms of that service before sending sensitive vault content.

  • The API key, settings, chat history, and optional embedding index are stored in Obsidian plugin data.
  • Chat requests may send the conversation plus enabled selection, current-note, keyword-search, and semantic-search context to the configured provider.
  • When semantic retrieval is enabled, Markdown chunks are sent to the configured embeddings endpoint. Their text, metadata, and returned vectors are stored in the local plugin data index.
  • Agent requests may send tool definitions, tool arguments, and tool results to the configured provider.
  • Read tools do not change vault files. Editing commands and Agent write tools only write after an explicit user action or confirmation.
  • The project does not implement telemetry or analytics.

Development

npm ci
npm run dev

Before submitting a change, run the same automated quality gate used by the project:

npm run verify

npm run verify checks formatting, linting, TypeScript, the production build, unit tests, release metadata, and required release assets. Local Obsidian smoke testing is separate and can be prepared with npm run deploy:test.

The codebase keeps UI, provider execution, Obsidian adapters, structured context, prompt composition, retrieval, and tools in separate modules. See the implementation plan, stage status, and architecture decisions for details.

Release status

Vault Loom is available in the Obsidian Community Plugins directory. The latest release is published on GitHub with the required Obsidian assets. See the release guide for the release process.

License

Vault Loom is available under the MIT License.

Sponsors