Agent Client for Obsidian: ACP Agents Inside Your Vault

The copy-paste gap Agent Client is built to close

The usual way to use a coding agent on your notes is to open a terminal, point the agent at a folder, and then paste note contents back and forth. Agent Client removes the pasting. The README describes the core loop plainly: mention notes with @ and let the agent read and edit them in your vault. The target user is someone who already has Claude Code, Codex or Gemini CLI installed and authenticated, and who treats an Obsidian vault as a working directory rather than a reading app. That is a narrower audience than "Obsidian users who want AI". The plugin does not ship a model, an API key or a chat backend. It launches the agent you already have as a child process and speaks ACP to it, so the quality of the answers is your agent's, not the plugin's. If you have never installed one of those CLIs, the plugin has nothing to talk to.

How ACP splits the work between plugin and agent

Agent Client is built on the Agent Client Protocol by Zed, and the README states the plugin launches locally installed agents as child processes. That single sentence defines the architecture. The plugin is the client half of ACP: it renders the conversation, the permission banners, the mode and model selectors, and the diff view. The agent is the server half, and it keeps its own tooling. The README is explicit that MCP servers, Agent Skills and slash commands come from the agent, with nothing to configure in the plugin. That is the design bet: the plugin does not reimplement tool use or command handling, so a new capability in your agent shows up in Obsidian without a plugin update. The README extends this to agents themselves, noting that a new ACP-compatible agent can be added as a custom entry without a plugin update. Seven presets ship in the box: Claude Code, Codex, Gemini CLI, Mistral Vibe, OpenCode, Kiro and Hermes Agent.

Note mentions, wikilink context and where the filesystem is touched

The @ mention is the mechanism that ties the agent to the vault. The README says mentions use fuzzy search over note names, paths and aliases, and that the active note is auto-mentioned down to the exact lines you selected. Two details matter here. First, the README states that [[links]] inside mentioned notes are surfaced as paths so the agent can decide which ones to read. The plugin does not follow the link graph for you; it hands over the paths and lets the agent choose. Second, and more important for anyone auditing this, the README says the filesystem is only probed read-only for the Auto-detect button, and that all note reading and writing goes through Obsidian's vault API. So vault access is mediated by Obsidian rather than by direct file reads. The agent can still run terminal commands, and the README is upfront that this is the core of what the plugin does, not a side effect.

Installing it and pointing it at an agent

The README gives a short installation path. Open Settings, then Community Plugins, then Browse, search for "Agent Client", click Install, then Enable. Getting started is three steps. First, install and authenticate an agent by following its setup guide on the project site; the README links separate pages for Claude Code, Codex, Gemini CLI, Mistral Vibe, OpenCode, Kiro, Hermes Agent and custom agents. Second, open Settings, Agent Client and check the agent's path, where Auto-detect usually finds it. Third, click the robot icon in the ribbon and start chatting. For pre-release builds, the README documents the BRAT route: install the BRAT plugin, go to Settings, BRAT, Add Beta Plugin, and paste the repository path. That matters because the most recent release listed is 0.13.0-preview.1, a preview tag, while 0.12.1 is the latest stable-looking version. If you want the stable line, take the Community Plugins route and leave BRAT alone.

Permission prompts, auto-allow and the real security boundary

This is the section to read twice. The README states that the agents have the same full system access they have in a terminal. The plugin does not sandbox them. What it adds is visibility: every permission request is surfaced so you can approve or reject each action, from a banner or with a hotkey, and Auto-allow permissions is off by default. Turning it on skips those prompts entirely. The README's own wording is to enable it only if you understand the implications, and that is the honest framing. There is a second boundary worth naming: the README says what leaves your machine is what you send to your agent's provider, meaning your messages, mentioned notes and attachments. Mentioning a note is a send action, not a local read. API keys are stored in Obsidian's Keychain rather than as plain text, according to the README. None of this is unusual for a tool that runs a CLI agent, but it does mean the plugin inherits every risk the agent already carries.

Where Agent Client is the wrong tool

The first hard limit is platform. The README states the plugin is desktop-only, so Obsidian on iOS or Android is out. The second is that it depends on an external binary. If your agent is not installed, not authenticated, or not on the path the plugin expects, there is no fallback: the plugin has no built-in model to degrade to. The third is behavioural. Sessions are saved locally and the README notes that resuming or forking past sessions is agent-dependent, so session history is not a uniform feature across the seven presets. If you need guaranteed resume behaviour, test it on your specific agent before relying on it. There is also a scope question. If your notes live in a vault and your agent's value comes from a code repository with tests and a build, then pointing a chat at the vault folder gives the agent less to work with than running it in the repo would. The README's New chat in directory feature addresses exactly this by letting a chat target any directory, including a code project, while still accepting @ mentions from the vault.

How this differs from an MCP-based note server

The obvious alternative approach is to skip the plugin and expose your vault to your agent through a filesystem or MCP server, then keep working in the terminal. The difference is where the conversation lives and who arbitrates writes. With an MCP server, the agent talks to a tool endpoint and the terminal is still your interface; you see tool calls as log lines. Agent Client moves the interface into Obsidian and renders note edits as word-level diffs in the chat, per the README, so a change to a note is presented as a reviewable diff rather than a completed write. It also centralises approval: permission prompts arrive in the chat pane, and the Session Manager lists every open conversation with live status icons including waiting for permission. The trade-off is that you are now maintaining a plugin alongside your agent, and the plugin only works inside the Obsidian desktop app. An MCP server works from any client that speaks MCP. If portability across editors matters more than seeing diffs next to your notes, the server route is the better fit.

Licence, upgrade cadence and what to verify first

The repository is Apache-2.0, which permits commercial use and modification and includes an explicit patent grant, with the usual requirements around notices and changed files. That is a permissive licence, and it is the licence of the plugin, not of the agents it launches; Claude Code, Codex and the rest carry their own terms, and the README's setup guides are the place to check those. On maintenance, the release list shows 0.12.0 in early August, 0.12.1 two weeks later, and 0.13.0-preview.1 in early September, which reads as an active but pre-1.0 project where minor versions can still move behaviour. There is no changelog in the supplied material, so I cannot tell you what changed between 0.12.1 and 0.13.0-preview.1. Treat that as the gap to close before upgrading: read the release notes on the repository, and if you depend on a specific agent preset, confirm it still resolves its path after the upgrade. The Auto-detect button and the agent path field under Settings, Agent Client are the two things to re-check after any version bump.

Editorial conclusion

Adopt Agent Client if you already run an ACP agent locally, work on a desktop OS, and want note edits reviewed as diffs rather than applied silently. Do not adopt it if you need mobile Obsidian, or if you are not comfortable granting a child process the same system access it has in a terminal. Before installing, run your agent's own setup guide to confirm it is authenticated, then check the agent path under Settings, Agent Client and leave Auto-allow permissions off until you have watched one full session's permission prompts.

Official sources

1. License: Apache-2.0
2. Project website
3. RAIT-09/obsidian-agent-client on GitHub
4. README
5. Releases