Claudian

An Obsidian plugin that embeds AI coding agents (Claude Code, Codex, Grok Build, 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.

Features & Usage

Open Claudian interface from the ribbon icon or command palette. Everything works like your familiar coding agent, Claude Code, Codex, Grok Build, OpenCode, and Pi — talk to the agent, and it reads, writes, edits, searches and run commands in your vault.

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

Zen Mode — Collapse the sidebar holding Claudian and the chat moves to a compact composer at the bottom of your notes, with a one-line activity preview and the conversation one click away.

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

@mention — Type @ to reference vault files, folders and other Claudian sessions.

Side Chat (/side or /btw) — Explore a separate, temporary conversation with follow-ups and tools while keeping the main chat unchanged.

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

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

Collaboration — Collab is now a standalone plugin. See Claudian Collab.

Requirements

• At least one of the following harnesses:
  • Claude Code
  • 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)

Claudian now supports OpenCode v2, OpenCode v1 support will end on October 30, 2026. See the OpenCode v2 migration guide.

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.
• 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 their configured services.

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 Code 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 Code CLI path.

For Codex on macOS, auto-detection also checks ChatGPT.app in /Applications and ~/Applications, including its nested codex-cli/CodexCLI.app runtime. A configured CLI path or shared PATH entry takes precedence.

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.

Authentication fails while the CLI subscription works

Claude can report authentication_failed inside Obsidian while the selected CLI works with a subscription in a terminal. An ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN inherited from the system environment takes precedence over subscription sign-in, so pointing Claudian at another CLI path does not help. The chat error includes the same recovery steps.

In Settings → Providers → Claude → Custom variables, add an empty assignment for the conflicting credential so Claude falls back to the subscription:

ANTHROPIC_API_KEY=

Use ANTHROPIC_AUTH_TOKEN= instead when that is the inherited credential. Override only credentials you intend to disable, and keep these assignments out of the shared environment so other providers are unaffected.

When asking for help, share the variable names involved rather than their secret values.

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 and sole composition root
├── composition/                 # Host objects and view wiring shared by app and features
├── app/                         # Startup, conversations, settings, and storage
├── core/                        # Provider-neutral execution, registry, and type contracts
│   ├── execution/               # Run, session snapshot, and interaction primitives
│   ├── providers/               # Provider registry and workspace services
│   ├── process/                 # CLI discovery and managed child processes
│   ├── prompt/                  # Prompt and context encoding
│   ├── auxiliary/               # Shared provider auxiliary services
│   └── ...                      # bootstrap, commands, rpc, security, storage, tools, types
├── providers/
│   ├── claude/                  # Claude Agent SDK adaptor, native history, plugins
│   ├── codex/                   # Codex shared app-server adaptor, JSON-RPC, JSONL history
│   ├── grok/                    # Grok Build ACP adaptor, native history, models, and tools
│   ├── opencode/                # OpenCode ACP and HTTP adaptors, shared server
│   ├── pi/                      # Pi RPC adaptor, model discovery, JSONL history
│   └── acp/                     # Agent Client Protocol shared mechanics
├── features/
│   ├── chat/                    # Sidebar chat: tabs, workspace lifecycle, controllers, renderers
│   ├── inline-edit/             # Inline edit modal and provider-backed edit services
│   └── settings/                # Settings shell, provider tabs, Vault skill management
├── shared/                      # Reusable UI components, settings controls, mention/dropdown
├── i18n/                        # Internationalization (10 locales)
├── utils/