Claudian

An Obsidian plugin that embeds AI coding agents (Claude Code, Codex, Grok, Opencode, Pi, and more to come) in your vault. Your vault becomes the agent's working directory — file read/write, search, bash, and multi-step workflows all work out of the box. Visit claudian.md to learn more.

Features & Usage

Open the chat sidebar from the ribbon icon or command palette. Select text and use the hotkey for inline edit. Everything works like your familiar coding agent, Claude Code, Codex, Grok, Opencode, and Pi — talk to the agent, and it reads, writes, edits, and searches files in your vault.

Inline Edit — Select text or start at the cursor position + hotkey to edit directly in notes with word-level diff preview.

Slash Commands & Skills — Type / or $ for reusable prompt templates or Skills from user- and vault-level scopes.

@mention - Type @ to mention anything you want the agent to work with, including vault files, subagents, and files in external directories.

Plan Mode — Toggle via Shift+Tab. The agent explores and designs before implementing, then presents a plan for approval.

Instruction Mode (/instruction) — Refined custom instructions added from the chat input.

MCP Servers — Connect external tools through each coding agent's native CLI-managed MCP configuration.

Tabs & Session Management — Use multiple tabs in single-panel mode or a persistent session manager beside the chat in dual-pane mode.

Collab Mode — Collaborate on shared projects with other Claudian users. Learn more.

Requirements

• At least one of the following harnesses:
  • Claude Code CLI
  • Codex CLI
  • Grok Build
  • OpenCode
  • Pi
• A compatible subscription or API provider, such as OpenRouter, Kimi, GLM, or DeepSeek etc.
• Obsidian v1.13.0+
• Desktop only (macOS, Linux, Windows)
• Collab Mode requires Git

Installation

From Obsidian Community Plugins (recommended)

1. Open Obsidian → Settings → Community plugins → Browse
2. Search for "Claudian" and click Install
3. Enable the plugin

Or install directly from the community plugin page.

From source (development)

1. Clone this repository into your vault's plugins folder:

   cd /path/to/vault/.obsidian/plugins
   git clone https://github.com/YishenTu/claudian.git
   cd claudian
   

2. Install dependencies and build:

   npm install
   npm run build
   

3. Enable the plugin in Obsidian:

   • Settings → Community plugins → Enable "Claudian"

Development

# Watch mode
npm run dev

# Production build
npm run build

Privacy & Data Use

• Sent to API: Your input, attached files, images, and tool call outputs. Depending on the selected provider, data is sent to Anthropic (Claude), OpenAI (Codex), xAI (Grok), or the providers configured in OpenCode or Pi. The destination can be configured through provider settings and environment variables.
• Collab LAN traffic: When you explicitly Host or synchronize a Collab Project, Project Git data and authenticated coordination metadata travel directly between invited teammates' devices on the local network. Collab Mode itself does not send Project data to a Claudian cloud service or any third party.
• No telemetry or unsolicited background activity: Claudian does not run telemetry beacons. UI polling timers read local Obsidian/editor selection state only. Network activity is limited to explicit provider runtime work, configured MCP endpoints, provider SDK/CLI calls needed to answer your requests, and explicitly started Collab LAN work.

Troubleshooting

The following sections use Claude Code as an example.

Provider CLI not found

If Claudian cannot auto-detect a provider CLI, verify that the CLI is installed and available to GUI applications through PATH. Typical errors include spawn claude ENOENT and Claude CLI not found. This issue is common with Node version managers (nvm, fnm, volta).

Leave the CLI path setting empty first so Claudian can auto-detect the CLI. If auto-detection fails, find the executable path and set it in Settings → Advanced → Claude CLI path.

Note: On Windows, avoid .cmd and .ps1 wrappers. Use claude.exe for native installs, or cli-wrapper.cjs for package-manager installs. cli.js is only a legacy fallback for older Claude Code npm packages.

Alternative: Add your Node.js bin directory to PATH in Settings → Environment → Custom variables.

npm CLI and Node.js not in the same directory

When using an npm-installed provider CLI, make sure its executable and Node.js are available from the same environment. Check their paths:

dirname $(which claude)
dirname $(which node)

If the paths differ, GUI apps like Obsidian may not find Node.js.

Either:

1. Install the native binary (recommended).
2. Add the Node.js path in Settings → Environment: PATH=/path/to/node/bin.

More help

For provider-specific installation and configuration guidance, refer to the provider documentation linked in the Requirements section. If you have a feature request or run into a bug, please submit a GitHub issue.

Architecture

src/
├── main.ts                      # Plugin entry point
├── app/                         # Application services, storage, and lazy Collab infrastructure
├── core/                        # Provider-neutral runtime, registry, and type contracts
│   ├── runtime/                 # ChatRuntime interface and approval types
│   ├── providers/               # Provider registry and workspace services
│   ├── auxiliary/               # Shared provider auxiliary services
│   ├── bootstrap/               # Plugin bootstrap wiring
│   ├── security/                # Approval utilities
│   └── ...                      # commands, prompt, storage, tools, types
├── providers/
│   ├── claude/                  # Claude SDK adaptor, prompt encoding, storage, MCP, plugins
│   ├── codex/                   # Codex app-server adaptor, JSON-RPC transport, JSONL history
│   ├── grok/                    # Grok Build ACP adaptor, native history, models, and tools
│   ├── opencode/                # Opencode adaptor
│   ├── pi/                      # Pi RPC adaptor, model discovery, JSONL history
│   └── acp/                     # Agent Client Protocol shared transport
├── features/
│   ├── chat/                    # Sidebar chat: tabs, controllers, renderers
│   ├── collab/                  # Collab sidebar, review, conflict, and access UI
│   ├── inline-edit/             # Inline edit modal and provider-backed edit services
│   └── settings/                # Settings shell with provider tabs
├── shared/                      # Reusable UI components and modals
├── i18n/                        # Internationalization (10 locales)
├── types/                       # Shared ambient types
├── utils/                       # Cross-cutting utilities
└── style/                       # Modular CSS

Contributing

Issues and focused pull requests are welcome. Issues are the preferred starting point: describe the problem, reproduction steps, and environment clearly so it can be investigated.

Before opening a pull request, please read the contribution guide. Pull requests must explain the problem, the proposed solution, why the approach is appropriate, and how the change was validated. Pull requests that add a new provider are not accepted; the guide explains this maintenance and product-quality boundary in detail.

Star History