obsidian-wikilinks 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sven Depickere
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,207 @@
+# obsidian-wikilinks
+
+Resolve `[[wikilinks]]` typed in a Codex, Claude Code, or OpenCode prompt to
+absolute paths in your Obsidian vault, and inject them as context so the agent
+reads the right notes.
+
+This is a **coding-agent** plugin (it teaches Codex / Claude Code / OpenCode
+about `[[ ]]`), not an Obsidian-app plugin.
+
+## How it works
+
+The prompt is scanned for `[[...]]`, each target is fuzzy-matched against note
+and folder names in your vault, and the resolved absolute paths are added to the
+prompt as extra context. The agent can then read the referenced notes when they
+are relevant to your request.
+
+All hosts share one resolver, `hooks/wikilink-resolver.py`:
+
+- Codex and Claude Code run it as a `UserPromptSubmit` hook.
+- OpenCode runs it from `plugin/obsidian-wikilinks.js` on the `chat.message`
+  hook, which appends the resolution as a synthetic text part.
+
+## Install in Codex
+
+```bash
+codex plugin marketplace add DepickereSven/obsidian-wikilinks
+codex plugin add obsidian-wikilinks@depickeresven-obsidian-wikilinks
+```
+
+Start a new thread, run `/hooks`, and review and trust the plugin's
+`UserPromptSubmit` hook when Codex asks. Installed command hooks do not run until
+they have been trusted.
+
+## Install in Claude Code
+
+```bash
+claude plugin marketplace add DepickereSven/obsidian-wikilinks
+claude plugin install obsidian-wikilinks@depickeresven-obsidian-wikilinks
+```
+
+## Install in OpenCode
+
+### From npm (recommended)
+
+```bash
+opencode plugin obsidian-wikilinks
+```
+
+That installs the package and adds it to your config. Or add it by hand:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["obsidian-wikilinks"]
+}
+```
+
+Use `~/.config/opencode/opencode.json` for every project, or `opencode.json` in
+a repo for that project only.
+
+> The package is not on npm yet. Until it is published, use one of the local
+> options below, or publish it yourself from a checkout with `npm publish`.
+
+### From a local checkout
+
+OpenCode loads any `.js` / `.ts` file in a plugin directory, and follows
+symlinks. Clone the repo once, then link the plugin:
+
+```bash
+git clone https://github.com/DepickereSven/obsidian-wikilinks.git ~/.config/opencode/obsidian-wikilinks
+mkdir -p ~/.config/opencode/plugin
+ln -s ~/.config/opencode/obsidian-wikilinks/plugin/obsidian-wikilinks.js ~/.config/opencode/plugin/
+```
+
+Use `.opencode/plugin/` instead of `~/.config/opencode/plugin/` to enable it for
+a single project only.
+
+Alternatively, reference the checkout from your config instead of symlinking —
+`plugin` entries accept `file://` URLs and paths relative to the config file:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["file:///Users/you/src/obsidian-wikilinks/plugin/obsidian-wikilinks.js"]
+}
+```
+
+The plugin finds `hooks/wikilink-resolver.py` next to itself, in the checkout or
+in `node_modules`. If you copy the `.js` file somewhere on its own, point it at
+the resolver with
+`OBSIDIAN_WIKILINKS_RESOLVER=/path/to/hooks/wikilink-resolver.py`.
+
+In the common case, no configuration is needed on any host. The plugin reads
+Obsidian's own vault registry and uses your active vault automatically.
+
+## Examples
+
+If your vault contains `Projects/Website Redesign.md`, this prompt:
+
+```text
+Summarize [[Website Redesign]] and list the next actions.
+```
+
+injects the note's absolute path so the agent can read and summarize it.
+
+You can reference several notes, headings, and aliases in one prompt:
+
+```text
+Compare [[Research/AI Agents#Open questions]] with
+[[Projects/Website Redesign|the project brief]].
+```
+
+The heading and alias are ignored during path lookup. Both note paths are added
+to the prompt context. Folder wikilinks work too:
+
+```text
+Review the notes in [[Meetings]] and prepare a weekly summary.
+```
+
+When a name is ambiguous, the plugin provides up to three candidate paths. If
+there is no match, it says so instead of guessing.
+
+## Vault selection
+
+Vault path resolution order:
+
+1. The current host's explicit override:
+   - Codex: `~/.codex/obsidian-wikilinks.json`
+   - Claude Code: `~/.claude/obsidian-wikilinks.json`
+   - OpenCode: `~/.config/opencode/obsidian-wikilinks.json`
+     (or `$OPENCODE_CONFIG_DIR` / `$XDG_CONFIG_HOME` when set)
+2. The other hosts' config files, as a compatibility fallback
+3. `$OBSIDIAN_VAULT` environment variable
+4. Obsidian's vault registry — auto-detected (prefers the open vault, else most
+   recently opened). Cross-platform (macOS / Windows / Linux).
+5. `~/Documents/Obsidian` (default fallback)
+
+You only need an explicit override if you have **multiple vaults** and want to
+pin a specific one. Create the config file for your host with:
+
+```json
+{ "vault": "/Users/you/Documents/Obsidian" }
+```
+
+The plugin itself is identical on every device. Update Claude Code with
+`claude plugin update obsidian-wikilinks`. Re-run the Codex `plugin add` command
+to install an updated version there. For OpenCode, re-run `opencode plugin
+obsidian-wikilinks`, or `git pull` in the checkout.
+
+## Environment variables
+
+| Variable                        | Purpose                                                      |
+|---------------------------------|--------------------------------------------------------------|
+| `OBSIDIAN_VAULT`                | Vault path, used when no host config file sets one           |
+| `OBSIDIAN_WIKILINKS_RESOLVER`   | Path to `wikilink-resolver.py` (OpenCode only)               |
+| `OBSIDIAN_WIKILINKS_PYTHON`     | Python interpreter to use (default `python3`, OpenCode only) |
+| `OBSIDIAN_WIKILINKS_TIMEOUT_MS` | Resolver timeout in ms (default `10000`, OpenCode only)      |
+
+## Development
+
+```bash
+npm test          # smoke tests on Node
+npm run test:bun  # same tests on Bun, the runtime OpenCode uses
+```
+
+No dependencies to install: the plugin uses Node/Bun built-ins and the resolver
+is standard-library Python.
+
+## Releasing
+
+CI runs the test suite on Node 20/22/24 and on Bun for every push and pull
+request, and checks that the packed tarball ships both `plugin/` and `hooks/`.
+
+To cut a release:
+
+```bash
+npm version patch     # or minor / major
+git push --follow-tags
+gh release create "v$(node -p 'require("./package.json").version')" --generate-notes
+```
+
+`npm version` also rewrites the Claude Code and Codex manifests through
+`scripts/sync-versions.mjs`, so all three stay on one version. Publishing the
+GitHub release triggers `.github/workflows/publish.yml`, which re-runs the
+tests, verifies the tag matches `package.json`, refuses to overwrite a version
+already on npm, and publishes with provenance.
+
+The workflow authenticates through **npm trusted publishing** (OIDC), so no
+token is stored in the repository. One-time setup: on npmjs.com, open the
+package's *Settings -> Trusted publishers*, and add this repository with
+workflow `publish.yml`.
+
+Trusted-publisher settings live on the package, so they can only be configured
+once the package exists. Do the **first** publish by hand from a checkout with
+`npm publish --access public`, then wire up the trusted publisher and let the
+workflow handle every release after that.
+
+To use a granular access token instead, save it as the `NPM_TOKEN` secret and
+uncomment the `NODE_AUTH_TOKEN` block in the workflow.
+
+Use the workflow's manual trigger (`workflow_dispatch`) with *dry run* enabled
+to rehearse a publish without releasing anything.
+
+## Requirements
+
+- `python3` on PATH (standard-library only; no pip installs).
+- OpenCode only: no extra dependencies — the plugin uses Node/Bun built-ins.

package/hooks/hooks.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/wikilink-resolver.py"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/wikilink-resolver.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Prompt hook: resolve [[wikilinks]] in the prompt to Obsidian vault files.
+
+Reads the hook JSON on stdin, scans the prompt for [[...]] references,
+fuzzy-matches them against note names in the vault, and emits the resolved
+absolute paths as additionalContext so the agent can read the right files.
+
+Hosts: Claude Code and Codex run this as a UserPromptSubmit hook. OpenCode runs
+it through plugin/obsidian-wikilinks.js, which feeds the same stdin payload and
+reads the same stdout JSON.
+
+Vault path resolution order:
+  1. The current host's config file (~/.claude, ~/.codex or ~/.config/opencode)
+  2. The other hosts' config files (compatibility fallback)
+  3. $OBSIDIAN_VAULT environment variable
+  4. Obsidian's own vault registry (auto-detected, cross-platform)
+  5. ~/Documents/Obsidian (default)
+"""
+import difflib
+import json
+import os
+import re
+import sys
+
+CONFIG_NAME = "obsidian-wikilinks.json"
+
+
+def opencode_config_dir():
+    explicit = os.environ.get("OPENCODE_CONFIG_DIR")
+    if explicit:
+        return os.path.expanduser(explicit)
+    xdg = os.environ.get("XDG_CONFIG_HOME") or os.path.expanduser("~/.config")
+    return os.path.join(xdg, "opencode")
+
+
+CONFIG_FILES = {
+    "claude": os.path.expanduser("~/.claude/" + CONFIG_NAME),
+    "codex": os.path.expanduser("~/.codex/" + CONFIG_NAME),
+    "opencode": os.path.join(opencode_config_dir(), CONFIG_NAME),
+}
+SKIP_DIRS = {".obsidian", ".trash", ".git", ".vault-meta"}
+WIKILINK = re.compile(r"\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]")
+
+
+def obsidian_registry_paths():
+    """Candidate locations of Obsidian's obsidian.json across platforms."""
+    home = os.path.expanduser("~")
+    candidates = [
+        os.path.join(home, "Library", "Application Support", "obsidian", "obsidian.json"),  # macOS
+        os.path.join(os.environ.get("APPDATA", ""), "obsidian", "obsidian.json"),            # Windows
+        os.path.join(home, ".config", "obsidian", "obsidian.json"),                          # Linux
+    ]
+    return [p for p in candidates if p and os.path.isfile(p)]
+
+
+def autodetect_vault():
+    """Read Obsidian's vault registry; prefer the open vault, else most recent."""
+    for path in obsidian_registry_paths():
+        try:
+            with open(path) as f:
+                vaults = json.load(f).get("vaults", {})
+        except (json.JSONDecodeError, OSError):
+            continue
+        valid = [v for v in vaults.values() if os.path.isdir(v.get("path", ""))]
+        if not valid:
+            continue
+        valid.sort(key=lambda v: (bool(v.get("open")), v.get("ts", 0)), reverse=True)
+        return valid[0]["path"]
+    return None
+
+
+def detect_host():
+    """Which agent invoked us; decides whose config file wins."""
+    host = os.environ.get("OBSIDIAN_WIKILINKS_HOST", "").strip().lower()
+    if host in CONFIG_FILES:
+        return host
+    if os.environ.get("OPENCODE") or os.environ.get("OPENCODE_CONFIG_DIR"):
+        return "opencode"
+    if os.environ.get("PLUGIN_ROOT"):
+        return "codex"
+    return "claude"
+
+
+def config_file_order():
+    """Current host's config first, the other hosts' files as fallbacks."""
+    host = detect_host()
+    return [CONFIG_FILES[host]] + [v for k, v in CONFIG_FILES.items() if k != host]
+
+
+def get_vault():
+    for config_file in config_file_order():
+        if not os.path.isfile(config_file):
+            continue
+        try:
+            with open(config_file) as f:
+                cfg = json.load(f)
+            vault = cfg.get("vault", "")
+            if vault:
+                return os.path.expanduser(vault)
+        except (json.JSONDecodeError, OSError):
+            pass
+    env = os.environ.get("OBSIDIAN_VAULT", "")
+    if env:
+        return os.path.expanduser(env)
+    detected = autodetect_vault()
+    if detected:
+        return detected
+    return os.path.expanduser("~/Documents/Obsidian")
+
+
+def build_index(vault):
+    index = []  # (stem, relpath, abspath)
+    for root, dirs, files in os.walk(vault):
+        dirs[:] = [d for d in dirs if d not in SKIP_DIRS and not d.startswith(".")]
+        for d in dirs:
+            abspath = os.path.join(root, d)
+            relpath = os.path.relpath(abspath, vault)
+            index.append((d, relpath, abspath + os.sep))
+        for f in files:
+            if f.startswith("."):
+                continue
+            abspath = os.path.join(root, f)
+            relpath = os.path.relpath(abspath, vault)
+            stem = os.path.splitext(f)[0]
+            index.append((stem, relpath, abspath))
+    return index
+
+
+def normalize(s):
+    return re.sub(r"[^a-z0-9]", "", s.lower())
+
+
+def resolve(target, index):
+    t = target.strip()
+    t_lower = t.lower()
+    t_md = t_lower if t_lower.endswith(".md") else t_lower + ".md"
+    t_norm = normalize(t)
+
+    # 1. exact stem match (case-insensitive)
+    hits = [e for e in index if e[0].lower() == t_lower]
+    # 2. exact relative path match (with or without .md)
+    if not hits:
+        hits = [e for e in index if e[1].lower() in (t_lower, t_md)]
+    # 3. substring match on stem
+    if not hits:
+        hits = [e for e in index if t_lower in e[0].lower()]
+    # 4. normalized containment ("Backend search" ~ "Back-end search vs ...")
+    if not hits and t_norm:
+        hits = [e for e in index if t_norm in normalize(e[0])]
+    # 5. fuzzy match: full stems, then stem prefixes of target length
+    if not hits:
+        stems = {e[0]: e for e in index}
+        close = difflib.get_close_matches(t, stems.keys(), n=3, cutoff=0.6)
+        if not close:
+            prefixes = {}
+            for stem in stems:
+                prefixes.setdefault(stem[: len(t)], stem)
+            close = [prefixes[p] for p in
+                     difflib.get_close_matches(t, prefixes.keys(), n=3, cutoff=0.6)]
+        hits = [stems[c] for c in close]
+    return hits[:3]
+
+
+def main():
+    try:
+        payload = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    prompt = payload.get("prompt", "")
+    targets = WIKILINK.findall(prompt)
+    if not targets:
+        sys.exit(0)
+
+    vault = get_vault()
+    if not os.path.isdir(vault):
+        sys.exit(0)
+
+    index = build_index(vault)
+    lines = []
+    for target in dict.fromkeys(targets):  # dedupe, keep order
+        hits = resolve(target, index)
+        if not hits:
+            lines.append(f"[[{target}]] -> no match found in vault {vault}")
+        elif len(hits) == 1:
+            lines.append(f"[[{target}]] -> {hits[0][2]}")
+        else:
+            opts = ", ".join(h[2] for h in hits)
+            lines.append(f"[[{target}]] -> ambiguous, candidates: {opts}")
+
+    context = (
+        "Obsidian wikilink resolution (vault: " + vault + "):\n"
+        + "\n".join(lines)
+        + "\nRead the resolved file(s) when their content is relevant to the request."
+    )
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": context,
+        }
+    }))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "obsidian-wikilinks",
+  "version": "0.2.0",
+  "description": "Resolve Obsidian [[wikilinks]] in coding-agent prompts to local vault paths and inject them as context.",
+  "type": "module",
+  "main": "plugin/obsidian-wikilinks.js",
+  "exports": {
+    ".": "./plugin/obsidian-wikilinks.js",
+    "./server": "./plugin/obsidian-wikilinks.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "node test/smoke.mjs",
+    "test:bun": "bun test/smoke.mjs",
+    "check:versions": "node scripts/sync-versions.mjs --check",
+    "sync:versions": "node scripts/sync-versions.mjs",
+    "version": "node scripts/sync-versions.mjs && git add .claude-plugin/plugin.json .codex-plugin/plugin.json",
+    "prepublishOnly": "npm run check:versions && npm test"
+  },
+  "files": [
+    "plugin",
+    "hooks",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "obsidian",
+    "wikilinks",
+    "notes",
+    "context",
+    "opencode",
+    "opencode-plugin"
+  ],
+  "author": {
+    "name": "Sven Depickere",
+    "url": "https://github.com/DepickereSven"
+  },
+  "homepage": "https://github.com/DepickereSven/obsidian-wikilinks",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DepickereSven/obsidian-wikilinks.git"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/DepickereSven/obsidian-wikilinks/issues"
+  }
+}

package/plugin/obsidian-wikilinks.js

@@ -0,0 +1,128 @@
+/**
+ * OpenCode plugin: resolve [[wikilinks]] in a prompt to Obsidian vault paths.
+ *
+ * Thin wrapper around hooks/wikilink-resolver.py, the same resolver used by the
+ * Claude Code and Codex UserPromptSubmit hooks. The Python script owns all
+ * vault detection and matching logic; this file only bridges OpenCode's
+ * `chat.message` hook to it.
+ */
+import {spawn} from "node:child_process"
+import {existsSync} from "node:fs"
+import {homedir} from "node:os"
+import path from "node:path"
+import {fileURLToPath} from "node:url"
+
+const WIKILINK = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/
+const PYTHON = process.env.OBSIDIAN_WIKILINKS_PYTHON || "python3"
+const TIMEOUT_MS = Number(process.env.OBSIDIAN_WIKILINKS_TIMEOUT_MS || 10000)
+
+/** Locate wikilink-resolver.py, whether the plugin is symlinked, copied, or installed by another host. */
+function findResolver() {
+    const explicit = process.env.OBSIDIAN_WIKILINKS_RESOLVER
+    if (explicit) return existsSync(explicit) ? explicit : null
+
+    const candidates = []
+    const here = path.dirname(fileURLToPath(import.meta.url))
+    // Repo layout: <root>/plugin/obsidian-wikilinks.js -> <root>/hooks/wikilink-resolver.py
+    for (let dir = here, i = 0; i < 5; i++, dir = path.dirname(dir)) {
+        candidates.push(path.join(dir, "hooks", "wikilink-resolver.py"))
+        if (dir === path.dirname(dir)) break
+    }
+    // Copied next to the plugin file
+    candidates.push(path.join(here, "wikilink-resolver.py"))
+    // Installed by another host on the same machine
+    const home = homedir()
+    for (const base of [
+        path.join(home, ".config", "opencode", "obsidian-wikilinks"),
+        path.join(home, ".claude", "plugins", "obsidian-wikilinks"),
+        path.join(home, ".codex", "plugins", "obsidian-wikilinks"),
+    ]) {
+        candidates.push(path.join(base, "hooks", "wikilink-resolver.py"))
+    }
+    return candidates.find(existsSync) || null
+}
+
+/** Run the resolver with the hook payload on stdin; resolve to its additionalContext, or null. */
+function resolveWikilinks(script, prompt) {
+    return new Promise((resolve) => {
+        let child
+        try {
+            child = spawn(PYTHON, [script], {
+                stdio: ["pipe", "pipe", "ignore"],
+                env: {...process.env, OBSIDIAN_WIKILINKS_HOST: "opencode"},
+            })
+        } catch {
+            return resolve(null)
+        }
+
+        let out = ""
+        const done = (value) => {
+            clearTimeout(timer)
+            resolve(value)
+        }
+        const timer = setTimeout(() => {
+            child.kill()
+            done(null)
+        }, TIMEOUT_MS)
+
+        child.stdout.on("data", (chunk) => (out += chunk))
+        child.on("error", () => done(null))
+        child.on("close", () => {
+            try {
+                const context = JSON.parse(out).hookSpecificOutput?.additionalContext
+                done(typeof context === "string" && context ? context : null)
+            } catch {
+                done(null)
+            }
+        })
+
+        child.stdin.on("error", () => {
+        })
+        child.stdin.end(JSON.stringify({prompt}))
+    })
+}
+
+let partCounter = 0
+
+function partID() {
+    partCounter += 1
+    const stamp = Date.now().toString(36)
+    const rand = Math.random().toString(36).slice(2, 10)
+    return `prt_wikilink_${stamp}${partCounter.toString(36)}${rand}`
+}
+
+/** @type {import("@opencode-ai/plugin").Plugin} */
+export const ObsidianWikilinksPlugin = async () => {
+    return {
+        "chat.message": async (_input, output) => {
+            const prompt = output.parts
+                .filter((part) => part.type === "text" && !part.synthetic && part.text)
+                .map((part) => part.text)
+                .join("\n")
+            if (!prompt || !WIKILINK.test(prompt)) return
+
+            const script = findResolver()
+            if (!script) return
+
+            const context = await resolveWikilinks(script, prompt)
+            if (!context) return
+
+            output.parts.push({
+                id: partID(),
+                sessionID: output.message.sessionID,
+                messageID: output.message.id,
+                type: "text",
+                text: context,
+                synthetic: true,
+            })
+        },
+    }
+}
+
+// Default export shape required by opencode for npm and file:// plugin specs
+// (`{ id, server }`); the named export above keeps plugin-directory loading
+// working on older opencode versions that scan named exports.
+export default {
+    id: "obsidian-wikilinks",
+    server: ObsidianWikilinksPlugin,
+}