🔮 Loredex for Obsidian

The Obsidian and MCP dashboard layer for loredex — shared memory, handoffs, and focused views for coding-agent teamwork.

loredex ecosystem  ·  📖 loredex (CLI + core)  ·  🖥️ Desktop app  ·  🔮 Obsidian plugin (you are here)

Part of the loredex ecosystem — the CLI, Claude Code plugin, vault spec, and all core logic live in the main repo: ahmedtawfeeq1/loredex. This plugin embeds that package as a library and re-hosts it inside Obsidian.

Loredex is the universal control system for coding-agent teamwork across products and projects. This plugin is the visual dashboard and in-app MCP layer that lets teams browse shared memory, track handoffs, and work from focused views inside Obsidian:

🚀 Quick Actions

Related MCP server: Obsidian MCP Server

📑 Table of Contents

• Quick Actions

• Why this plugin exists

• Requirements

• Network use disclosure

• Install

• Setup

• Commands

• Settings

• Security model

• Development

• Related

• License

🧭 Why This Plugin Exists

• 📊 Native dashboard — one click (ribbon or command) opens _index/Dashboard.base, the Obsidian Bases database loredex generates: latest notes, open handoffs, by-project cards, stale list. Sortable, filterable, 100% native UI.

• 🔔 Handoff badge — the status bar shows how many cross-team handoffs are open across the product. Click it to open the dashboard.

• ⇅ Vault sync — one command pulls the shared vault repo (rebase + autostash), rebuilds the indexes, commits, and pushes. Same conflict-free merge driver the CLI uses for generated files.

• 🤖 MCP server inside Obsidian — serves the vault to coding agents (Claude Code, Cursor, Codex CLI) over Streamable HTTP on localhost. All six loredex MCP tools (vault_search, vault_note, handoffs_open, handoff_consume, product_state, vault_store) plus one only Obsidian can provide: active_note — the note you're looking at right now.

Requirements

• Obsidian ≥ 1.9 (the dashboard uses the core Bases plugin) · desktop only (isDesktopOnly — the plugin shells out to git and reads the vault through Node fs)

• A loredex vault (npx loredex init — see the main repo)

Network use disclosure

When the MCP server is enabled (default: on), the plugin listens on 127.0.0.1 only — it never binds a public interface and never makes outbound network requests. Every request must carry a bearer token generated on first load (Settings → Loredex). Turn the server off in settings and the plugin opens no sockets at all. Git sync runs git against whatever remote you configured for your vault repo; the plugin adds no remotes.

Install

Not yet in the community plugin directory. Two options:

BRAT (recommended — auto-updates): install BRAT, then Add beta plugin → ahmedtawfeeq1/loredex-obsidian.

Manual: grab main.js + manifest.json from the latest release, drop them in <vault>/.obsidian/plugins/loredex/, reload Obsidian, enable the plugin.

Setup

1. Open your loredex vault (~/Loredex by default) as an Obsidian vault, if you haven't already.

2. Enable the plugin. A bearer token is generated automatically.

3. Run the command “Loredex: Copy MCP server config for coding agents” and add it to your agent. Recommended: user-scope config so the token never lands in a committed .mcp.json:

claude mcp add --scope user --transport http loredex-obsidian \
  http://127.0.0.1:28428/mcp --header "Authorization: Bearer <your-token>"

Agents connected this way search and file into the vault while Obsidian is open — no separate process. (Without Obsidian running, agents use the CLI's stdio server instead: npx -y loredex mcp. Same tools, minus active_note.)

Commands

Settings

Security model

The vault is treated as untrusted input end to end — same rules as the loredex CLI. Note content returned to agents is framed as data, never instructions, control characters are stripped, and lengths are bounded. Note paths are resolved with realpath and must land inside the vault (symlink escapes rejected). The server is stateless: every request gets a fresh MCP server instance reading current vault state.

Development

npm install          # installs the loredex core from npm
npm run typecheck
npm run build        # bundles src/main.ts → main.js (CJS, obsidian external)
npm run smoke        # boots the HTTP server against a temp vault, drives a real MCP session
npm run dev          # esbuild watch mode

npm run smoke is the fast loop — it proves auth, initialize, tools/list, and a real vault_search without launching Obsidian.

Related

• loredex — the main repo: CLI, Claude Code plugin, MCP server, vault spec, and all core logic (this plugin embeds it as a library)

License

MIT © Ahmed Tawfeeq — PM & Head of AI, Founder @ genudo.ai