Nexus turns your Obsidian vault into an MCP-enabled workspace. It exposes safe, structured tools that AI copilots can call to read/write notes, manage folders, run searches, and maintain long-term memory—all while keeping data local to your vault.
Nexus is the successor to Claudesidian. Legacy installs in
.obsidian/plugins/claudesidian-mcp/still work.
- Two-Tool Architecture – Just 2 MCP tools (
getTools+useTools) replace 40+ individual tools, reducing upfront token cost by ~95%. - Native Chat View – Stream tool calls, branch conversations, and manage models directly inside Obsidian.
- Inline AI Editing – Select text, right-click or use hotkey, and transform it with AI instructions.
- Workspace Memory – Workspaces, states, and traces in
.nexus/(sync-friendly JSONL + local SQLite cache). - Workflow Automation – Workspace workflows can bind saved prompts, run on recurring schedules, catch up after downtime, and be tested with
Run now. - Local Semantic Search – Desktop-only embeddings via sqlite-vec vector search—no external API calls. Search notes and conversation history.
- Full Vault Operations – Create, read, update, delete notes, folders, frontmatter, and batch edits.
- Multi-Provider Support – Anthropic, OpenAI, Google, Groq, Mistral, OpenRouter, Perplexity, Requesty, plus local servers (Ollama, LM Studio). All providers use lightweight direct HTTP—no SDK dependencies.
- Multi-Vault Ready – Independent MCP instances per vault.
- Task Management – Workspace-scoped projects and tasks with DAG dependency tracking, priority, assignees, due dates, vault note linking, and a built-in settings UI for managing projects and tasks.
- Apps – Extend Nexus with downloadable tool domains like ElevenLabs for AI audio generation.
Platform Notes
| Feature | Desktop | Mobile |
|---|---|---|
| Native Chat | ✅ | ✅ |
| Inline AI Editing | ✅ | ✅ (command palette only) |
| MCP Bridge (Claude Desktop) | ✅ | — |
| Local Providers (Ollama/LM Studio) | ✅ | — |
| Semantic Embeddings | ✅ | — |
| Cloud Providers | ✅ (real streaming) | ✅ (buffered fallback) |
Nexus exposes exactly 2 tools to MCP clients like Claude Desktop:
| Tool | Purpose |
|---|---|
toolManager_getTools |
Discovery – Returns schemas for requested agents/tools |
toolManager_useTools |
Execution – Runs tools with unified context |
- ~95% token reduction in upfront schemas (~15,000 → ~500 tokens)
- Works great with small context window models (local LLMs)
- Context-first design captures memory/goal for every operation
Every useTools call includes context that helps maintain continuity:
{
workspaceId: string; // Scope identifier (name or UUID)
sessionId: string; // Session name (system assigns standard ID)
memory: string; // Conversation essence (1-3 sentences)
goal: string; // Current objective (1-3 sentences)
constraints?: string; // Rules/limits (1-3 sentences, optional)
}| Agent | Purpose | Tools |
|---|---|---|
| contentManager | Note reading/editing | read, write, update |
| storageManager | File/folder management | list, createFolder, move, copy, archive, open |
| searchManager | Search operations | searchContent, searchDirectory, searchMemory |
| memoryManager | Workspace/state management | createWorkspace, listWorkspaces, loadWorkspace, updateWorkspace, archiveWorkspace, runWorkflow, createState, listStates, loadState |
| promptManager | Custom prompts & LLM | listModels, executePrompts, listPrompts, getPrompt, createPrompt, updatePrompt, archivePrompt, generateImage, subagent |
| canvasManager | Canvas operations | read, write, update, list |
| taskManager | Project & task management | createProject, listProjects, updateProject, archiveProject, createTask, listTasks, updateTask, moveTask, queryTasks, linkNote |
| elevenlabs (app) | AI audio generation with dynamic model selection | textToSpeech, listVoices, soundEffects, generateMusic |
- Download the latest release assets:
manifest.json,styles.css,main.js,connector.js - Place them in
.obsidian/plugins/nexus/(or keep legacy.obsidian/plugins/claudesidian-mcp/) - Enable Nexus in Obsidian Settings → Community Plugins
- Restart Obsidian after first install
Add the Nexus server to your claude_desktop_config.json:
{
"mcpServers": {
"nexus-your-vault": {
"command": "node",
"args": [
"/path/to/Vault/.obsidian/plugins/nexus/connector.js"
]
}
}
}Or use the one-click setup: Settings → Nexus → Get Started → MCP Integration → Add Nexus to Claude
After adding, fully quit and relaunch Claude Desktop.
- Configure a provider in Settings → Nexus → Providers
- Open chat via ribbon icon or command palette (Nexus: Open Nexus Chat)
- Type
/for tools,@for custom agents,[[to link notes - Tool calls stream live with collapsible result panels
Edit selected text directly in your notes using AI:
- Select text in any note
- Trigger via:
- Right-click → Edit with AI (requires "Native menus" disabled in Obsidian settings)
- Command palette → Edit selection with AI
- Enter instruction (e.g., "Make this more concise", "Translate to French")
- Generate – Watch streaming preview with cancel option
- Review & Apply – Edit the result, retry, or apply to replace original text
| Feature | Description |
|---|---|
| Model Selection | Dropdown to choose from configured providers |
| Streaming Preview | See AI output as it generates |
| Cancel Support | Stop generation mid-stream |
| Editable Result | Modify AI output before applying |
| Retry | Regenerate with same or new instruction |
| Undo | Standard Ctrl/Cmd+Z after applying |
All data lives in .nexus/ inside your vault:
.nexus/
├── conversations/*.jsonl # Chat history (syncs across devices)
├── workspaces/*.jsonl # Workspace events
└── cache.db # SQLite cache (auto-rebuilt, not synced)
- Each tool call is tagged to a workspace automatically via context
- Create/load workspaces and save immutable state snapshots via tools or chat UI
- Workflows live inside workspace settings and can include:
- plain-language
when+steps - optional saved prompt binding
- optional recurring schedule: hourly, daily, weekly, or monthly
- catch-up behavior for missed runs after Obsidian was closed
- plain-language
Run nowis available from both the workflow list and the workflow editor- Scheduled and manual workflow runs create a fresh chat conversation titled
[workspace - workflow - YYYY-MM-DD HH:mm] - Workflow prompts are scoped to the workflow run itself and are not auto-injected just because the workspace was loaded
- Archive workspaces and states for cold storage (restorable)
- No external database required
Use workflows when you want reusable, workspace-scoped operating procedures instead of one-off prompts.
Each workflow can:
- describe when it should be used
- store workflow-specific steps in plain language
- bind an optional saved prompt/agent
- run immediately with
Run now - run automatically on a recurring schedule
Supported schedules:
- Hourly: every
Nhours - Daily: at a selected hour and minute
- Weekly: on a selected weekday, hour, and minute
- Monthly: on a selected day of month, hour, and minute
Catch-up behavior for scheduled workflows:
- Skip missed runs: ignore missed schedule slots
- Run latest missed: create one catch-up run for the newest missed slot
- Run all missed: create one run per missed slot in order
AI copilots can also trigger workflows through the workspace tool surface with memoryManager.runWorkflow.
Use it when you already know the workspace and want to execute a saved workflow programmatically. The tool accepts:
workspaceIdworkflowIdorworkflowName- optional
openInChat
In addition to MCP/chat task tools, Nexus now includes a built-in task management UI inside Settings → Nexus → Workspaces.
Open a workspace, then:
- Click Manage Projects
- Open a project card
- Review tasks in the project task table
- Use the checkbox to mark tasks done or reopen them
- Click Edit to open the full task editor page with a back button
Current UI flow:
- Workspace detail → task/project entrypoint
- Project cards → one card per workspace project
- Project detail → task table with status, priority, due date, assignee, and actions
- Task detail → dedicated editor for title, description, status, priority, due date, assignee, tags, project, and parent task
Notes:
- The database remains the source of truth for tasks
- This is the v1 management surface; there is no markdown/Kanban note sync yet
- Task edits made in chat and in settings operate on the same underlying task data
Use searchManager.searchContent with semantic: true for meaning-based search:
- Desktop only – Embeddings run locally via iframe-sandboxed transformers.js
- Model:
Xenova/all-MiniLM-L6-v2(384 dimensions, ~23MB, cached in browser IndexedDB) - Vectors: Stored in
.nexus/cache.dbvia sqlite-vec for fast similarity search - First run downloads the model (requires internet); subsequent runs are fully offline
- Watch the status bar for indexing progress; click to pause/resume
Use searchManager.searchMemory to search across past conversation turns and tool call traces:
| Mode | Scope | Use Case |
|---|---|---|
| Discovery | Workspace-wide | "What have I discussed about authentication?" |
| Scoped | Session + N-turn window | "What did I just ask about this file?" |
- Conversations are chunked into Q&A pairs and embedded in real-time as you chat
- Multi-signal reranking: semantic similarity + recency + session density + note references
- Background backfill indexes existing conversations automatically
- Works with the same local embedding model—no external API calls
Apps are downloadable tool domains that extend Nexus with third-party integrations. Each app brings its own set of tools, credentials, and API connections — install only what you need.
Configure apps in Settings → Nexus → Apps. Enter your API key, hit Validate, and the modal will confirm which capabilities your key supports (and flag any missing permissions).
| App | Tools | What It Does |
|---|---|---|
| ElevenLabs | textToSpeech, listVoices, soundEffects, generateMusic | AI audio generation — convert text to speech, create sound effects, and generate music. Audio files save directly to your vault. |
Have an idea for a new app? Open an issue with the app-request label describing the integration you'd like to see.
Want to build your own? See Building Apps — an agentic prompt you can feed to your AI coding assistant to create a new app from scratch. It covers the full pattern: manifest, agent class, tools, vault file saving, and registration.
- Each vault runs its own MCP server with key
nexus-[vault-name] - Add one entry per vault in your MCP client config
- Keep vaults open to keep their servers reachable
- MCP server binds locally only—no remote listeners
- All file operations stay inside the active vault
- Network calls only for remote LLM providers (per your API keys)
- Embeddings download once, then run fully on-device
| Issue | Solution |
|---|---|
| Server not found | Settings → Nexus → Get Started → MCP Integration → Add Nexus to Claude, then restart Claude Desktop |
| Pipes not created | Ensure Obsidian is open; Windows uses nexus_mcp_<vault> named pipes |
| WebLLM crashes | Currently disabled due to WebGPU bug on Apple Silicon; use Ollama or LM Studio |
| Legacy install | Paths to .obsidian/plugins/claudesidian-mcp/connector.js still work |
npm install # Install dependencies
npm run dev # Development build with watch
npm run build # Production build
npm run test # Run tests
npm run lint # Run ESLintAll LLM provider SDKs have been replaced with direct HTTP via a shared ProviderHttpClient. No SDK dependencies are required — this keeps the bundle small and avoids version conflicts.
See CLAUDE.md for architecture details and contribution notes.
MIT License - see LICENSE for details.
Questions or issues? Open a GitHub issue with your OS, Obsidian version, and any console logs.
