fegger/obsidian_ollama
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Refactor README with comprehensive documentation

Browse Source
This commit is contained in:
Florian Egger
2026-05-07 19:10:15 +02:00
parent 3ab326ffc2
commit 79db888f9e
1 changed files with 99 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+99 -32
View File
@@ -1,64 +1,131 @@
# Ollama Chat Plugin for Obsidian
A plugin that integrates Ollama with Obsidian to create a chat interface that can access your vault content.
A plugin that integrates [Ollama](https://ollama.ai) with [Obsidian](https://obsidian.md) to create a chat interface that can access your vault content contextually.
## Features
- Chat with Ollama models directly in Obsidian
- Vault context search - the assistant can reference your notes
- Tool integration - create files based on chat responses
- Streaming responses
- Customizable model and URL settings
- **Chat with local AI models** — Interact with Ollama models directly in Obsidian's sidebar
- **Vault context search** — The assistant automatically searches your notes using weighted scoring (headings, frontmatter titles/tags, content)
- **Tool integration** — AI can create files in your vault via the `create_file` tool
- **Streaming responses** — Real-time token streaming for a responsive chat experience
- **Configurable settings** — Customize model, URL, search limits, and message history
## Installation
1. Install the plugin via Obsidian's community plugins
2. Make sure you have Ollama installed and running
### From Source
## Setup
1. Clone this repository into your Obsidian vault's `.obsidian/plugins/` folder:
```bash
cd .obsidian/plugins
git clone <repo-url> obsidian-ollama
cd obsidian-ollama
npm install
npm run build
```
2. Enable the plugin in Obsidian: Settings → Community plugins → Ollama Plugin
1. **Install Ollama**: Follow the instructions at [ollama.ai](https://ollama.ai) to install Ollama
2. **Start Ollama service**: `ollama serve`
3. **Pull a model**: `ollama pull llama3` (or any other model you prefer)
## Prerequisites
1. **Install Ollama**: Follow the instructions at [ollama.ai](https://ollama.ai)
2. **Start Ollama**: `ollama serve`
3. **Pull a model**: `ollama pull llama3` (or any model you prefer)
## Configuration
1. Open the plugin settings via Obsidian's settings panel
2. Configure the Ollama URL (default: `http://localhost:11434`)
3. Configure the model name (default: `llama3`)
4. Restart the plugin if needed
Open Settings → Ollama Plugin to configure:
| Setting | Default | Description |
|---------|---------|-------------|
| Ollama URL | `http://localhost:11434` | Your Ollama instance URL |
| Model | `llama3` | Model to use for chat |
### Internal Settings
| Setting | Default | Description |
|---------|---------|-------------|
| Vault Search Limit | `3` | Max notes returned for context |
| Max Message History | `50` | Messages kept in conversation context |
## Usage
1. Click the ribbon icon to open the chat view
2. Type your message in the input box
3. Press Enter or click Send to send your message
4. Click the "New Chat" button to start a fresh conversation
1. Click the chat icon in the left ribbon to open the chat view
2. Type your message and press **Enter** or click **Send**
3. Click **New Chat** to start a fresh conversation
### Vault Context
When you send a message, the plugin automatically searches your vault for relevant notes and includes them as context. The search uses weighted scoring:
- **Headings** — 5x weight
- **Frontmatter title** — 3x weight
- **Frontmatter tags** — 2.5x weight
- **First paragraph** — 1.5x weight
- **General content** — 1x weight
### Tools
The plugin exposes a `create_file` tool that allows the AI to create new markdown files in your vault. Paths are validated for safety (no `.obsidian`/`.git` access, no path traversal).
## Supported Models
Any model supported by Ollama should work, including:
Any Ollama-supported model works. Popular choices:
- llama3
- llama2
- mistral
- codellama
- etc.
| Model | Best For |
|-------|----------|
| `llama3` | General chat |
| `mistral` | Fast responses |
| `codellama` | Code assistance |
| `gemma` | Lightweight local use |
## Development
To build from source:
```bash
npm install # Install dependencies
npm run build # Compile TypeScript
npm run watch # Watch mode for development
npm test # Run tests (Jest)
npm run lint # Lint with ESLint
npm run format # Format with Prettier
```
### Project Structure
```
src/
├── main.ts # Plugin entry point and settings
├── chat-view.ts # Chat UI and message handling
├── ollama-client.ts # Ollama API communication
├── vault-indexer.ts # Vault search and scoring
├── tool-executor.ts # Tool execution (create_file)
├── error-handler.ts # Centralized error handling
├── utils.ts # Validation and logging utilities
├── types.ts # TypeScript type definitions
└── constants.ts # Default configuration
```
### Testing
The project includes tests for all major components. Run with:
```bash
npm install
npm run build
npm test
```
## Troubleshooting
- **Connection issues**: Ensure Ollama is running and accessible at the configured URL
- **Model not found**: Make sure you've pulled the model (`ollama pull <modelname>`)
- **Permission issues**: Check that your Obsidian vault has proper write permissions
| Issue | Solution |
|-------|----------|
| Connection refused | Ensure Ollama is running (`ollama serve`) |
| Model not found | Pull the model first (`ollama pull <model>`) |
| Permission errors | Check vault write permissions |
| Empty responses | Try a different model or check Ollama logs |
## Security
- File paths are validated to prevent access to `.obsidian/` and `.git/` directories
- Path traversal attempts (`..`) are blocked
- Absolute paths and Windows drive letters are rejected
- Maximum path length is enforced (200 characters)
## License