---

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

I want to...	Go here
Install the plugin fast	Install
Connect my agent to Obsidian's local MCP server	Setup
Understand how this fits into the full loredex framework	Main repo
See the visual story behind the product	loredex infographic gallery
Check security and localhost network behavior	Network use disclosure

📑 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

Use the main loredex repo for...	Use loredex-obsidian for...
Routing markdown into the vault, running adopt, route, curate, handoff, and the CLI MCP server	Opening the dashboard, syncing the vault from inside Obsidian, watching handoffs, and exposing active_note to agents
Setting the shared knowledge structure	Making that structure visible and agent-accessible where you actually read it

• 📊 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

Command	What it does
Open product dashboard	Opens _index/Dashboard.base — the native Bases database over every note, handoff, and project
Sync vault	git pull → rebuild indexes → commit → push
Copy MCP server config for coding agents	Clipboard-ready snippet with your port + token
Restart MCP server	Rebind after changing port/token

Settings

Setting	Default
MCP server	on	Streamable HTTP on localhost
Port	28428
Bearer token	generated	regenerate any time (then re-add the agent config)
Git sync	on	pull/commit/push during sync command
Handoff check interval	5 min	status-bar badge refresh

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