# AI Wiki — Obsidian Plugin

[Русская версия →](docs/README.ru.md)

Automatically builds and maintains a knowledge-base wiki from your notes using an AI assistant.

**Why AI Wiki:**
- **Offline by default** — works with Ollama or any local AI server; your notes never leave your machine
- **Grows with your notes** — every Ingest adds new topics and updates existing ones automatically
- **Transparent** — watch every AI step in real time in the sidebar panel
- **Two AI backends** — local (Ollama / OpenAI-compatible) or Claude AI; switch any time in settings

> Supported backends: **Ollama / OpenAI-compatible** (fully local) · **Claude Agent** (Anthropic cloud)

---

## What it does

AI Wiki reads your notes and maintains a structured knowledge base (wiki) alongside them. Think of it as an assistant that reads what you write and keeps a living reference document up to date.

| Feature | What it does |
|---|---|
| **Ingest** | Reads an open note, extracts key topics (people, tools, processes, terms), creates or updates wiki pages |
| **Query** | Answers a question using your wiki as context; results shown in the sidebar with cross-links |
| **Lint** | Reviews wiki pages for gaps, outdated content, and broken links; shows a report in the sidebar |
| **Fix** | After Lint — send an instruction in the sidebar chat to apply corrections |
| **Init** | Sets up a new knowledge area (domain) with the folder structure and index files |
| **Re-init** | Wipes and rebuilds a domain from scratch — useful after major source changes |
| **Format** | Cleans up any open markdown note (outside the wiki): headings, tables, frontmatter, image captions. Shows a preview before applying. Invariant: never adds or removes facts — only improves clarity |
| **Chat** | Interactive follow-up in the sidebar after Query or Lint |

Fix, Format, and Chat are launched from sidebar buttons, not the Command Palette.

> **Mobile:** only Query works on mobile. Ingest, Lint, Init, and Format are desktop-only.

---

## Security

### Shell execution

The Claude Agent backend starts an external process to run the Claude CLI:

- **What is executed:** the absolute path you configure in Settings → "Path to Claude Code" (e.g. `/home/user/iclaude.sh`). The path is validated to be absolute and free of traversal sequences before each spawn.
- **Why it's required:** the Claude Agent backend calls `claude` / `iclaude.sh` as a subprocess. There is no alternative to `child_process.spawn` for this architecture.
- **Your permissions:** the subprocess inherits your OS user's permissions — the same as running Claude CLI manually in a terminal.
- **First-run consent:** on first launch with Claude Agent selected, a confirmation dialog appears before anything runs. You can revoke consent by removing `shellConsentGiven` from the plugin's `local.json`.

### Vault access

The plugin reads only the folders you set as sources for each domain. It does not scan your entire vault.

---

## Quick start: Ollama (fully local)

No accounts or cloud services required — AI runs on your computer.

### 1. Install Ollama

Download from [ollama.com](https://ollama.com) and pull a model:

```bash
ollama pull llama3.2
```

### 2. Install the plugin

Copy the plugin folder into your vault:

```bash
# symlink for development
ln -s /path/to/obsidian-ai-wiki ~/.config/obsidian/Plugins/obsidian-ai-wiki
```

Or copy the folder to `<vault>/.obsidian/plugins/obsidian-ai-wiki/` manually.

### 3. Enable the plugin

Obsidian → Settings → Community plugins → find "AI Wiki" → enable.

### 4. Configure

Settings → AI Wiki:

| Setting | Value |
|---|---|
| Backend | Native Agent (OpenAI-compatible) |
| Base URL | `http://localhost:11434/v1` |
| API Key | `ollama` |
| Model | `llama3.2` |
| Temperature | `0.2` |
| Max tokens | `4096` |

### 5. Create a knowledge area (domain)

A domain is a pair: "source folder → wiki folder". The AI reads files from the source folder and writes wiki pages to the wiki folder.

Open the AI Wiki sidebar panel (ribbon icon or Command Palette → "Open panel"), then:

1. Click the **Init** button in the "Create" section
2. Enter a domain name (e.g. `work`)
3. Add source folder paths — the folders containing notes you want to turn into wiki
4. Click **Run** — the plugin creates the wiki folder and starts building pages

### 6. First Ingest

1. Open any note in Obsidian
2. In the sidebar, select your domain from the dropdown
3. Click the **Ingest** button
4. Watch progress in the sidebar — new wiki pages appear in the domain folder

---

## Quick start: Claude Agent

For users with [Claude Code CLI](https://claude.ai/code) installed.

### 1. Requirements

- Installed `iclaude.sh` / `iclaude` / `claude` (Claude Code CLI)

### 2. Install and enable the plugin

Same as steps 2–3 of the Ollama section above.

### 3. Configure

Settings → AI Wiki:

| Setting | Value |
|---|---|
| Backend | Claude Agent |
| Path to Claude Code | `/home/user/Documents/Project/iclaude/iclaude.sh` |
| Model | `sonnet` |
| Timeouts (seconds) | `300/300/900/3600/600` |

### 4. First Ingest

Same as step 6 of the Ollama section above.

---

## Sidebar panel

The sidebar is the main interface for AI Wiki. Open it via the ribbon (🧠 icon) or Command Palette → "Open panel".

### Sections

**Create** — click **Init** to set up a new knowledge domain (name, wiki folder, source paths).

**Fill / Maintain** — manage and populate an existing domain:
- Domain selector — choose which domain to work with
- **↻** refresh the domain list
- **📁+** manage source folders (add or remove)
- **♻** re-init: wipe all wiki pages and rebuild from sources
- 📜 open the domain log file
- 🗒 open the domain index file
- **Ingest** — process the currently open note
- **Lint** — review wiki quality and find gaps
- **Format** — clean up the currently open note's formatting

**Query** — type a question and click **Ask**. The answer appears in the sidebar with wiki cross-links. Use the **Chat** section below the result to refine or follow up.

---

## Commands (Command Palette)

| Command | Action |
|---|---|
| `AI Wiki: Open panel` | Show the sidebar panel |
| `AI Wiki: Ingest active file` | Ingest the currently open note *(desktop only)* |
| `AI Wiki: Query` | Ask a question via a dialog box |
| `AI Wiki: Lint domain` | Check wiki quality *(desktop only)* |
| `AI Wiki: Init domain` | Re-run init for an existing domain *(desktop only)* |
| `AI Wiki: Cancel operation` | Stop the current operation |

---

## Settings reference

### General (both backends)

| Setting | Description | Default |
|---|---|---|
| User prompt | Added to the system prompt of every operation | empty |
| Timeouts (seconds) | `ingest/query/lint/init/format`, slash-separated | `300/300/900/3600/600` |
| History limit | Max operations in sidebar history | `20` |
| Agent log (JSONL) | Log agent events to `!Wiki/_config/_agent.jsonl` (desktop only) | off |

### Domains

List of created domains with **Edit** / **Delete** buttons. Domain map is stored in `!Wiki/_config/_domain.json`.

### Backend selector

| Setting | Description | Default |
|---|---|---|
| Backend | `claude-agent` or `native-agent` (desktop). Mobile is forced to native-agent | `native-agent` |

### Claude Agent

| Setting | Description | Default |
|---|---|---|
| Path to Claude Code | Full absolute path to `iclaude.sh` / `iclaude` / `claude` | — |
| Model | Preset (`opus`/`sonnet`/`haiku`) or explicit ID (`claude-sonnet-4-6`). Shown when per-operation is off | claude default |
| Allowed tools | Comma-separated list passed to `--tools`. Empty = no restriction | `Read,Edit,Write,Glob,Grep` |
| Per-operation models | When on, configure model per operation (ingest/query/lint/init/format) | off |
| Per-operation: Model | Model for the specific operation | — |

### Native Agent

| Setting | Description | Default |
|---|---|---|
| Base URL | OpenAI-compatible endpoint. Ollama: `http://localhost:11434/v1` | `http://localhost:11434/v1` |
| API key | `ollama` for Ollama; `sk-...` for OpenAI | `ollama` |
| Model | Model name (`llama3.2`, `mistral`, `gpt-4o`, …). Shown when per-operation is off | `llama3.2` |
| Temperature | `0.0`–`1.0`. Low values (`0.1`–`0.3`) give more precise, factual answers | `0.2` |
| Per-operation models | When on, configure `model`/`maxTokens`/`temperature` per operation | off |
| Structured output retries | Retries on schema validation failure (0–3). Higher = more reliable on weaker models | `1` |

### Proxy (native-agent only)

| Setting | Description | Default |
|---|---|---|
| Use proxy | Route native-agent traffic through HTTP/HTTPS proxy. Not supported on mobile | off |
| Proxy URL | `http://proxy.example.com:8080` or `https://…` | — |
| Username | Optional, for basic-auth proxies | — |
| Password | Optional, stored locally in `local.json` | — |
| No-proxy hosts | CSV; supports exact host and `*.suffix`. Example: `localhost,127.0.0.1,*.internal` | — |

### Graph

| Setting | Description | Default |
|---|---|---|
| BFS depth | Query: hops from seed pages when collecting context. `0` = seeds only | `1` |
| Hub threshold | Lint: pages with more outgoing links than this are flagged as hubs | `20` |

### Developer (desktop only)

| Setting | Description | Default |
|---|---|---|
| Dev mode | Enable dev logger and evaluator after each operation | off |
| Evaluator model | Model used by the evaluator (same backend) | — |

---

## Sync

`local.json` (inside the plugin folder) stores machine-specific settings: the path to Claude CLI, API key, and selected backend. **Exclude `local.json` from sync** when using Obsidian Sync / git / Syncthing — otherwise settings will be overwritten on other machines.

The domain map (`!Wiki/_config/_domain.json`) lives inside the vault and syncs normally with your notes.

---

## Performance reference

Real-world measurements from a homelab inference server running **`deepseek-v4-flash:cloud`** via Native Agent (OpenAI-compatible endpoint). Numbers show what to expect at roughly 100–130 output tokens/second — a mid-range local or self-hosted GPU.

| Operation | Typical duration | LLM calls | Input tokens (avg/call) | Output tokens (avg/call) | Speed (tok/s) |
|---|---|---|---|---|---|
| **Query** | 4–14 s | 1 | ~6 800 | ~470 | ~100 |
| **Ingest** (1 note) | ~25 s | 2 | ~4 300 | ~1 200 | ~109 |
| **Init** (6–24 source files) | 6–27 min | 20–35 per session | ~5 700 | ~2 600 | ~122 |
| **Lint** (large domain) | ~60 min | 69 | ~14 300 | ~6 500 | ~128 |

> **Init** and **Lint** scale with the number of source files and wiki pages. A domain with 6 files takes ~6 min; 24 files — ~27 min. Lint scanned a large domain (69 LLM calls) in about 60 min.

### What affects speed

- **Model** — smaller/quantized models are faster; larger models produce better wiki quality
- **Inference server** — a local GPU is fastest; cloud APIs add network latency
- **Domain size** — Init and Lint time grows linearly with the number of files

---

## Documentation

- [docs/dev.md](docs/dev.md) — build, install, smoke-test checklist for developers
- [docs/README.ru.md](docs/README.ru.md) — Russian version of this README