Stop Switching Windows! Run Claude Code Inside Obsidian with Agent Client

Stop Switching Windows! Run Claude Code Inside Obsidian with Agent Client

Every developer knows the pain. You're deep in a technical note, mapping out a complex system architecture in Obsidian, when you need AI assistance. So you do what we've all been trained to do: Alt-Tab into a terminal, fire up Claude Code, lose your context, then struggle to paste insights back where they belong. Rinse and repeat twenty times a day.

What if that friction simply... disappeared?

What if your AI agents lived inside your knowledge base—where your notes, your research, your entire second brain already resides?

That's exactly what obsidian-agent-client delivers. Built on Zed's emerging Agent Client Protocol (ACP), this plugin doesn't just add AI chat to Obsidian. It fundamentally reimagines how developers interact with AI agents by embedding Claude Code, OpenAI Codex, Google Gemini CLI, and custom agents directly into your vault. No context switching. No copy-paste hell. Just seamless, note-aware intelligence where you actually work.

In this deep dive, I'll show you why this plugin is rapidly becoming the secret weapon for developers who take their Obsidian setup seriously—and exactly how to unleash its full potential.

What Is obsidian-agent-client?

obsidian-agent-client is an Obsidian plugin developed by RAIT-09 that bridges the gap between local AI agent tooling and your personal knowledge management system. It implements the Agent Client Protocol (ACP), an open standard originally created by Zed Industries to standardize how AI agents communicate with client applications.

Here's why this matters: before ACP, every AI agent was a silo. Claude Code spoke its own language. Codex did its own thing. Gemini CLI operated in isolation. The protocol changes everything by creating a universal interface—and this plugin makes Obsidian the first major knowledge base to speak that language natively.

The project is trending hard for three reasons:

1. Timing: Developers are exhausted by browser-based AI interfaces and want local, private, terminal-native tools
2. Protocol momentum: ACP is gaining traction as the "USB-C for AI agents"—one plug, infinite tools
3. Obsidian's explosion: With millions of users treating Obsidian as their IDE for thought, the demand for integrated AI has reached fever pitch

Unlike generic AI plugins that bolt a chatGPT clone onto your sidebar, obsidian-agent-client treats your entire vault as context. It understands @note references, respects your folder hierarchy, and lets agents execute terminal commands with results flowing back into your notes. This isn't chat-with-AI. This is AI-augmented knowledge work.

Key Features That Separate It From Generic AI Plugins

Let's dissect what makes this plugin technically distinctive:

Note-Aware Context with @Mentions

Most AI integrations treat your notes as dead text files. obsidian-agent-client implements dynamic note referencing using @notename syntax. When you type @architecture-decisions, the agent receives structured context about that specific note—not just its content, but its metadata, backlinks, and position in your knowledge graph. This transforms vague AI responses into precisely contextualized assistance.

Native Image Pipeline

Drag-and-drop or paste images directly into chat. The plugin handles base64 encoding, MIME type detection, and multimodal model handoff automatically. For developers documenting UI bugs, sharing screenshots of errors, or working with visual architectures, this eliminates the tedious upload-dowload dance.

Slash Command Integration

Agents expose their native / commands through the plugin interface. This means Claude Code's built-in tools, Codex's file operations, and Gemini's specialized commands all work without abstraction layers. You're not getting a dumbed-down API wrapper—you're getting the full agent surface area.

Multi-Agent Orchestration

Run Claude Code for reasoning-heavy tasks, Codex for code generation, and Gemini CLI for research—simultaneously, in separate panes. The plugin maintains isolated Node.js processes for each agent, preventing context contamination while letting you compare outputs side-by-side.

Floating Chat Architecture

The persistent, collapsible chat window uses Obsidian's workspace API to maintain state across workspace changes. Unlike modal dialogs that interrupt flow, this follows HUD (heads-up display) principles—always available, never intrusive.

Session History with Forking

Conversations are serialized as structured data, not just text logs. You can resume any session, fork it to explore alternatives (crucial for A/B testing prompts), or export to Markdown^{↗ Smart Converter} for permanent documentation.

Terminal Integration Without Leaving Obsidian

Agents execute shell commands through secure subprocess spawning, with stdout/stderr streamed back into chat in real-time. Combined with Obsidian's code block rendering, you get executable documentation—runbooks that actually run.

Zero-Config MCP Support

Model Context Protocol servers configured in your agents just work. No duplicate setup, no credential management in the plugin. The plugin respects agent-native configuration, maintaining single source of truth for your AI tooling.

Real-World Use Cases Where This Changes Everything

1. Architecture Decision Records That Write Themselves

You're evaluating three database options. You spawn Claude Code, reference your @performance-requirements and @budget-constraints notes, and have it generate a comparative analysis. The agent queries actual benchmark data via MCP tools, executes validation scripts through terminal integration, and outputs a ready-to-commit ADR as a new note. What took hours now takes minutes.

2. Living API Documentation

Maintain OpenAPI specs in Obsidian? Connect Codex to your spec files. When you @reference an endpoint note, Codex suggests implementation examples, generates test cases, and even executes curl commands to verify behavior—all within your documentation workspace. Your docs become executable specifications.

3. Bug Triage with Visual Context

Screenshot a production error. Paste it into chat with Gemini CLI. Reference your @deployment-config note. The agent cross-references logs via MCP, suggests root causes, and proposes fixes. Export the conversation as @incident-2024-001 for your post-mortem. Complete incident workflow without leaving your vault.

4. Multi-Agent Research Synthesis

Studying a new framework? Run Claude for conceptual understanding, Codex for code examples, and Gemini for ecosystem research simultaneously. Fork promising threads, merge insights into a @learning-rust master note. This is distributed cognition made tangible.

5. Automated Knowledge Gardening

Use slash commands to have agents refactor your vault: find duplicate concepts, suggest new links, generate MOCs (Maps of Content) from orphaned notes. Your second brain gets a custodial AI that maintains itself.

Step-by-Step Installation & Setup Guide

Method 1: Community Plugins (Recommended)

The simplest path for most users:

# No terminal needed for this method!

1. Open Settings → Community Plugins → Browse
2. Search for "Agent Client"
3. Click Install, then Enable
4. Restart Obsidian if prompted

Method 2: BRAT for Bleeding-Edge Features

For pre-release access to latest features:

# First, install BRAT plugin through Community Plugins
# Then in Obsidian:
# Settings → BRAT → Add Beta Plugin → Paste URL

1. Install BRAT via Community Plugins
2. Navigate to Settings → BRAT → Add Beta Plugin
3. Paste: https://github.com/RAIT-09/obsidian-agent-client
4. Enable Agent Client from your plugin list

Method 3: Manual Installation

For air-gapped environments or custom builds:

# Download from GitHub Releases page
# https://github.com/RAIT-09/obsidian-agent-client/releases

# Create plugin directory in your vault
mkdir -p "YourVault/.obsidian/plugins/agent-client/"

# Move downloaded files
cp main.js manifest.json styles.css "YourVault/.obsidian/plugins/agent-client/"

Then enable in Settings → Community Plugins.

Agent Setup: Claude Code Example

Here's the complete terminal workflow from the repository's quick start:

# Step 1: Install Claude Code itself
curl -fsSL https://claude.ai/install.sh | bash

# Step 2: Install the ACP adapter (critical!)
npm install -g @agentclientprotocol/claude-agent-acp

# Step 3: Authenticate (interactive)
claude
# Follow prompts to link your Anthropic account

# Step 4: Locate binaries for plugin configuration
which node              # macOS/Linux: /usr/local/bin/node
which claude-agent-acp  # macOS/Linux: /usr/local/bin/claude-agent-acp

# Windows equivalents:
# where.exe node
# where.exe claude-agent-acp

Critical configuration detail: In Settings → Agent Client, set:

• Node.js path: /usr/local/bin/node (your which node output)
• Claude Code path: /usr/local/bin/claude-agent-acp — NOT claude
  • This trips up many users: claude is the interactive CLI; claude-agent-acp is the protocol adapter
• API key: Optional if you authenticated via claude login; required for headless setups

Repeat similar flows for Codex, Gemini CLI, or custom agents like OpenCode, Qwen Code, Kiro, and Mistral Vibe.

REAL Code Examples from the Repository

The repository includes essential commands for development and agent installation. Let's examine them with detailed explanations.

Example 1: Agent Installation Pipeline

# Install Claude Code - the base interactive tool
curl -fsSL https://claude.ai/install.sh | bash

# Install the ACP protocol adapter - this is the bridge
npm install -g @agentclientprotocol/claude-agent-acp

What's happening here? The first command installs Anthropic's official Claude Code CLI—think of this as the "driver." The second installs the ACP adapter, which wraps that driver in a standardized protocol that obsidian-agent-client understands. This separation is elegant: Anthropic controls the AI, the open community controls the interface standard, and RAIT-09's plugin provides the Obsidian integration. You need both because the plugin doesn't speak "Claude" natively—it speaks ACP.

Example 2: Binary Discovery Commands

# macOS/Linux: find where binaries live in your PATH
which node              # Returns: /usr/local/bin/node
which claude-agent-acp  # Returns: /usr/local/bin/claude-agent-acp

# Windows: equivalent discovery
where.exe node              # e.g., C:\Program Files\nodejs\node.exe
where.exe claude-agent-acp  # e.g., C:\Users\You\AppData\Roaming\npm\claude-agent-acp.cmd

Why this matters: Obsidian plugins run in a sandboxed Electron environment with limited PATH inheritance. Hardcoding absolute paths ensures reliable agent spawning regardless of how you launched Obsidian. The which/where.exe dance prevents the dreaded "command not found" errors that plague cross-platform Node tooling. Pro tip: On macOS, if you use nvm, your Node path changes per shell session—use which node from the same terminal where you'll run agents, or better, symlink to /usr/local/bin/node.

Example 3: Plugin Development Workflow

# Clone and enter repository
git clone https://github.com/RAIT-09/obsidian-agent-client.git
cd obsidian-agent-client

# Install dependencies (Obsidian API, build tools, etc.)
npm install

# Start development build with hot reload
npm run dev

# Production build for distribution
npm run build

Under the hood: npm run dev likely uses esbuild or rollup with watch mode, rebuilding main.js on file changes. Obsidian's hot-reload detects main.js changes and refreshes the plugin without full app restart. The build command minifies and tree-shakes for the Community Plugins marketplace. For contributors, this means rapid iteration—modify TypeScript, see results in Obsidian within seconds.

Example 4: Plugin File Structure (Manual Install)

# Required files in your vault's plugin directory
VaultFolder/.obsidian/plugins/agent-client/
├── main.js        # Compiled plugin logic (entry point)
├── manifest.json  # Metadata: ID, version, minAppVersion
└── styles.css     # Custom CSS for chat UI, floating window

The manifest.json contract: Obsidian reads manifest.json to validate compatibility before loading main.js. It specifies the plugin ID (agent-client), version constraints, and which Obsidian API version you need. The styles.css scopes all custom UI elements—chat bubbles, floating window chrome, mention highlights—to prevent theme conflicts. This three-file structure is Obsidian's plugin standard, making manual installation predictable across all platforms.

Advanced Usage & Best Practices

Optimize Agent Context Windows

Your vault might have 10,000 notes. Agents have token limits. Strategic @mentioning beats brute-force vault dumping. Create hub notes that synthesize related concepts, then @mention those. This "context distillation" pattern maximizes agent effectiveness.

Leverage Session Forking for Prompt Engineering

When you get a great response, fork the session before continuing. This creates an immutable checkpoint. Iterate on the fork—if you hit a dead end, you haven't corrupted your productive thread. This is version control for conversations.

Combine with Obsidian's Native Power

Use Canvas alongside the floating chat. Drag AI-generated insights onto cards. Link them to existing notes. The plugin outputs Markdown—Obsidian's native blood type—so everything composes into your knowledge graph seamlessly.

Secure Your Agent Credentials

The plugin reads agent configs from their native locations. Never commit .env files or credential directories to Git. Use Obsidian's Sync or Git plugins with .gitignore rules that exclude sensitive paths.

MCP Server Orchestration

Since agents use their configured MCP servers, curate your server collection per agent. Give Claude Code access to documentation search and code execution. Give Codex file system and GitHub tools. Specialization beats generalization.

Comparison with Alternatives

The verdict: Generic plugins offer convenience but trap you in single-provider ecosystems. Terminal purists retain flexibility at massive friction cost. obsidian-agent-client occupies the golden mean: protocol-native flexibility, deep Obsidian integration, and local-first architecture.

FAQ

What is the Agent Client Protocol (ACP)?

ACP is an open standard by Zed Industries for standardized AI agent communication. Think HTTP for web servers, but for AI agents. It defines how clients (like this plugin) discover capabilities, send prompts, and receive structured responses from any compliant agent.

Do I need API keys for every agent?

Not necessarily. Claude Code supports CLI authentication (run claude and log in). Codex and Gemini may require API keys depending on their ACP adapter implementations. Check the setup guides for specifics.

Can I use this with self-hosted or local models?

Yes! The custom agents documentation covers OpenCode, Qwen Code, and others. Any tool implementing ACP or wrappable with an adapter can integrate.

Is my vault data sent to cloud services?

Only if you use cloud-hosted agents. The plugin itself is local. Claude Code can run with local authentication. For maximum privacy, choose self-hosted agents or local models through custom adapters.

Why does the plugin need Node.js path configuration?

Agents run as separate Node.js processes, not inside Obsidian's JavaScript^{↗ Bright Coding Blog} environment. The plugin spawns these processes and communicates via ACP over stdio. Hardcoded paths ensure reliable execution across different shell configurations.

Can I run multiple agents on the same note simultaneously?

Absolutely. The multi-session architecture isolates each agent in separate views. Compare Claude's reasoning against Codex's implementation approach in real-time, then synthesize the best of both.

What happens to my chat history?

Sessions are stored locally and can be exported as Markdown notes at any time. This transforms ephemeral AI conversations into permanent, searchable knowledge in your vault.

Conclusion: Your Vault, Supercharged

The obsession with "AI in every app" has produced countless shallow integrations—chat bubbles bolted onto unrelated products, desperate to check a feature box. obsidian-agent-client is the rare exception that earns its place through architectural coherence.

By building on ACP, it doesn't lock you into any single AI provider. By embedding in Obsidian, it respects your existing knowledge graph rather than creating yet another silo. By supporting terminal integration and MCP servers, it preserves the power of local tooling while eliminating context-switching friction.

For developers who've invested hundreds of hours curating their Obsidian vaults, this plugin isn't a nice-to-have. It's the missing link that makes your second brain actually think with you.

Ready to stop Alt-Tabbing and start integrating?

👉 Install obsidian-agent-client from the Community Plugins marketplace

👉 Star the repository on GitHub to follow development and contribute

👉 Read the full documentation for advanced agent configurations

The future of knowledge work isn't switching between tools. It's orchestrating intelligence where your knowledge already lives. This plugin gets you there today.

Have you integrated AI agents into your Obsidian workflow? Share your setup in the GitHub Discussions—the community is actively shaping how developers use this emerging protocol.