# Obsidian Agent Client: Run Claude Code, Codex, and Gemini CLI Inside Your Vault > Obsidian Agent Client is an Obsidian plugin that connects your locally installed AI coding agents to your vault via the Agent Client Protocol. You can mention notes with @, see what the agent edits as word-level diffs, and approve or reject each action without leaving Obsidian. **RAIT-09/obsidian-agent-client** — Bring AI agents into Obsidian via Agent Client Protocol (ACP), such as Claude Code, Codex and Gemini CLI. - Repository: https://github.com/RAIT-09/obsidian-agent-client - Website: https://rait-09.github.io/obsidian-agent-client/ - Stars: 2,439 · Forks: 223 - Language: TypeScript - License: Apache-2.0 - Published: 2026-09-10 · Updated: 2026-09-10 · Language: en - Canonical page: https://hysenlabs.com/projects/rait-09-obsidian-agent-client ## What Obsidian Agent Client Does The plugin wraps the Agent Client Protocol (ACP), an open protocol developed by Zed, and exposes it inside Obsidian's interface. When you open a chat window, the plugin launches your locally installed agent as a child process and maintains a session that persists for the duration of the conversation. The core use case is giving an AI agent direct access to your vault notes without copy-pasting. You mention a note by typing @ in the chat input; the plugin resolves the mention through fuzzy search over note names, paths, and aliases. The active note is auto-mentioned when you open a chat, down to the exact lines you selected. Links inside mentioned notes are surfaced as paths so the agent can decide which ones to read. Note edits the agent makes appear as word-level diffs in the chat window. You see the change before it is applied, and you can approve or reject each agent action from the same banner or with a keyboard shortcut. ## Supported Agents and the ACP Architecture The plugin ships nine presets: Claude Code, Codex, Gemini CLI, Mistral Vibe, OpenCode, Kiro, Hermes Agent, Pi, and Grok Build. You can also add any ACP-compatible agent as a custom entry without waiting for a plugin update. ACP is the protocol layer. Because it is an open standard, agents that adopt it work with the plugin immediately. The README makes this explicit: if a new agent ships ACP support tomorrow, you can add it as a custom entry. This matters because the plugin's value scales with the number of ACP-compatible agents, and the protocol is not controlled by the plugin's maintainer. Agents bring their own capabilities. MCP servers, Agent Skills, and slash commands that work in the agent's terminal interface work the same way inside the plugin. Nothing needs to be configured in the plugin to enable those features. This design means the plugin is a thin host layer, not a reimplementation of agent features. ## Installing Obsidian Agent Client The standard installation path uses Obsidian's Community Plugins system: 1. Open Settings, go to Community Plugins, click Browse 2. Search for "Agent Client" 3. Click Install, then Enable For pre-release versions, the README documents installation via BRAT. Install the BRAT plugin, go to Settings, BRAT, Add Beta Plugin, and paste https://github.com/RAIT-09/obsidian-agent-client. For manual installation, download main.js, manifest.json, and styles.css from the Releases page and place them in VaultFolder/.obsidian/plugins/agent-client/, then enable the plugin from Community Plugins. After installation, open Settings, go to Agent Client, and verify the agent's path. The README says Auto-detect usually finds the path. Click the robot icon in the ribbon to start a chat. For development, the build process uses: ```bash npm install npm run dev ``` For a production build: ```bash npm run build ``` ## Multi-Session Layout and Session Management The plugin supports running several agents at the same time in separate sessions. You can place chats in sidebar tabs, editor tabs, or floating windows, each with its own session and model. A hotkey cycles focus between sessions, and a broadcast option sends the same prompt to all active sessions simultaneously. The Session Manager panel lists every open conversation across all windows with live status icons. One icon state shown is waiting for permission, which means an agent has made a request that requires your approval before it can proceed. Clicking any entry in the Session Manager jumps to that conversation. You can also embed a live chat inside a note using a code block with persist enabled, and the conversation survives restarts. One-click agent buttons in notes fire prepared prompts, which can be useful for repetitive tasks tied to a specific document. ## Security Model and Data Handling The plugin is desktop-only and works by launching locally installed agents as child processes. Those agents have the same full system access they would have in a terminal. The plugin does not sandbox or restrict agent actions at the OS level. Permission prompts are shown for each agent action by default. Auto-allow permissions is an opt-in setting that is off by default. The README is direct about this: enable it only if you understand the implications. On shared machines, leaving Auto-allow off is the correct choice. Filesystem access through the plugin's own code is limited. The README states that the filesystem is only probed read-only for the Auto-detect button, and all note reading and writing goes through Obsidian's vault API. What leaves your machine is what you send to your agent's provider: messages, mentioned notes, and attachments. API keys are stored in Obsidian's Keychain, not as plain text in the vault or plugin configuration. ## Key Limitations to Check Before Adopting The plugin requires a locally installed agent. There is no built-in API fallback. If you have not installed and authenticated Claude Code, Codex, Gemini CLI, or another ACP-compatible agent on your machine, the plugin has nothing to connect to. WSL mode is documented for running agents inside WSL on Windows. The README mentions this as a supported configuration, which means the setup on Windows involves an additional step compared to macOS or Linux. Session history is described as agent-dependent. Forking past sessions is possible but depends on whether the specific agent supports that operation. The README does not list which agents support session forking and which do not. A useful comparison is direct terminal usage of the same agent. The terminal gives you the agent's full output, its file editing interface, and its tool calls without any intermediate layer. The plugin adds the @mention system for vault notes and the embedded chat UI. If you do not keep notes in Obsidian or do not find the @mention workflow valuable, the plugin adds complexity without benefit over working in a terminal. ## License and Maintenance The plugin is licensed under Apache-2.0. The repository was at version 0.13.0, released on 2026-09-14, with pre-release versions available through BRAT. The last push to the repository was on 2026-09-23, indicating recent activity. The build system uses esbuild and TypeScript, with vitest for testing and VitePress for documentation. The package.json shows dependencies on the @agentclientprotocol/sdk at version 0.28.1, which is the library that handles the ACP connection layer. When the ACP SDK updates, the plugin maintainer needs to follow. Documentation for each supported agent's setup is at rait-09.github.io/obsidian-agent-client/. Separate pages cover setup for Claude Code, Codex, Gemini CLI, and each other preset agent. ## Conclusion Obsidian Agent Client is worth installing if you already use a supported AI agent in a terminal and want to work alongside it in the same interface where you keep your notes. The security model is clear but demanding: once you grant an agent access, it has the same filesystem reach it has from a terminal, and Auto-allow permissions (off by default) removes the per-action approval step entirely. Install through Community Plugins, verify the agent's path with the Auto-detect button in Settings, and test with a disposable note before pointing an agent at a folder of important documents. ## FAQ ### Which AI agents does Obsidian Agent Client support? The plugin ships nine presets: Claude Code, Codex, Gemini CLI, Mistral Vibe, OpenCode, Kiro, Hermes Agent, Pi, and Grok Build. Any agent that supports ACP can be added as a custom entry without a plugin update. ### Does Obsidian Agent Client give agents access to my entire file system? Yes. The README states that agents have the same full system access they have in a terminal. The plugin surfaces per-action permission prompts so you can approve or reject each operation; Auto-allow permissions is off by default. ### How do I install Obsidian Agent Client without using Community Plugins? Download main.js, manifest.json, and styles.css from the GitHub Releases page and place them in VaultFolder/.obsidian/plugins/agent-client/. Then enable the plugin from Settings under Community Plugins. ## Sources - [License: Apache-2.0](https://github.com/RAIT-09/obsidian-agent-client/blob/master/LICENSE) - [Project website](https://rait-09.github.io/obsidian-agent-client/) - [RAIT-09/obsidian-agent-client on GitHub](https://github.com/RAIT-09/obsidian-agent-client) - [README](https://github.com/RAIT-09/obsidian-agent-client/blob/master/README.md) - [Releases](https://github.com/RAIT-09/obsidian-agent-client/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rait-09-obsidian-agent-client