obsidian-yolo: an agent-native AI assistant inside Obsidian

The gap YOLO fills in an Obsidian vault

Obsidian ships a text editor and a link graph. It does not ship a retrieval layer, a chat surface, or any notion of an agent that can act on your notes. The usual workaround is a second window with a chatbot, plus copy and paste. YOLO's pitch is that the assistant lives where the notes live.

The README frames the project as an "Agent-native AI assistant for Obsidian" covering chat, writing, knowledge base and orchestration. That word, agent-native, is the real scope claim. The 1.5 release notes describe an agent runtime with full tool calling, MCP, Skills, desktop Bash, subagents and web search. The 1.6 notes add on-device local embedding models, multiple knowledge bases, CLI chat on desktop, and a Learning Mode built on FSRS spaced repetition.

The audience is narrow but real: people whose notes already live in Obsidian and who want the model to read them without exporting anything. If your notes are in Notion, or you want an editor-agnostic assistant, the plugin's whole value proposition disappears.

How the agent, RAG and knowledge bases fit together

Three layers are visible from the README and the repository layout. The first is the plugin shell. It is a standard Obsidian community plugin: manifest.json declares it, main.js is the bundle, styles.css carries the styling, and the build produces those artifacts from src/ via esbuild.config.mjs. The repository also carries modules/ and runtime-components/ with their own build and typecheck scripts, which suggests the agent runtime is compiled separately from the plugin entry point rather than bundled into one file.

The second layer is retrieval. Vault RAG retrieves across the vault so answers are grounded in your own notes. Version 1.6 added on-device local embedding models and multiple knowledge bases, with the README stating you can "index without any API key" and that the Agent can auto-pick the right knowledge base by name. That is a meaningful design choice: local embeddings keep note content on the machine, but they also mean indexing cost moves to your CPU and the retrieval quality is whatever the bundled model gives you.

The third layer is the agent runtime. Tool calling, MCP servers, Skills, desktop Bash and subagents all sit on top of retrieval. The README also describes an external agent path in the other direction: MCP clients such as Hermes and OpenClaw can connect to YOLO's vault search, or delegate tasks to a configured YOLO agent. So the plugin is both an MCP client and something other tools can call into.

One detail worth flagging: the repository's package.json lists version 1.6.9.2 while the most recent release shown is 1.6.6.2. That is normal for a repository that bumps the version file ahead of a release, but it means the version string in package.json is not a reliable signal of what is published.

Installing YOLO and asking your vault a question

The README gives two installation paths. The recommended one is the community plugin store: open Obsidian Settings, go to Community Plugins, choose Browse, and search for "YOLO". Install it, enable it, then open the plugin settings and add an API key or sign in with ChatGPT or Gemini OAuth. The README links to key pages for OpenAI, Anthropic, Gemini and Groq.

The manual path is for people who want a specific build or cannot reach the store. Download main.js, manifest.json and styles.css from the releases page, then place them in a folder named obsidian-yolo inside your vault's plugin directory. The README gives the folder as `<vault>/.obsidian/plugins/obsidian-yolo/` and says to copy the three files into it, then enable the plugin in Obsidian Settings.

The README warns in a callout that YOLO cannot coexist with Smart Composer, so disable or uninstall that plugin first. This is not a soft preference; the README states it as a hard constraint.

Once the plugin is enabled, the README's quick start says to open the sidebar to chat, or to try Quick Ask by typing `@` in the editor. What you should see is a chat surface in the sidebar and, when you type `@`, an inline entry point that does not take you out of the note you are writing.

If you are building from source rather than installing a release, package.json defines the dev and build scripts. The build script runs a TypeScript check, a module typecheck, a runtime typecheck, a PostCSS styles build, the runtime and module builds, an esbuild production pass, and a runtime verification step. The repository lists `npm run build` as the entry point for that chain:

npm run build

The README does not document what the runtime verification step checks, so treat a green build as a build that passed its own checks rather than a guarantee about behaviour in your vault.

Smart Composer conflict, OAuth trust and the desktop-only features

The Smart Composer conflict is the most concrete limitation in the documentation. The README does not explain why the two plugins cannot coexist, only that you must disable or uninstall Smart Composer before using YOLO. If Smart Composer is part of your workflow, that is a migration decision, not a toggle.

Credentials are the second constraint. Configuration happens in plugin settings, which means API keys or OAuth sessions live inside your vault configuration. Anyone with filesystem access to the vault directory can read that. The README does not describe a keychain integration or a separate secrets store, so plan accordingly.

Third, several headline features are desktop-only. CLI chat, which drives a Claude Code, Codex, Hermes or Pi CLI you are already signed into, is labelled desktop in both the feature table and the release notes. Desktop Bash is in the same category. On mobile the plugin may still work for chat and retrieval, but the agent features that make it distinctive are not there. The search data shows people looking for an Android build; the README makes no Android-specific claim, and the desktop labels suggest the answer depends on which feature you mean.

Finally, the roadmap is honest about what is not done. Annotation Mode, a built-in assistant with auto-compaction and scheduled tasks, a better AI whiteboard, and voice input with meeting notes are all unchecked. The README does not document rollback behaviour if an agent action edits a note you did not intend to change, which is the risk that matters most when Bash and tool calling are enabled.

YOLO versus Smart Composer and the plain-chat approach

The obvious alternative is Smart Composer, the plugin the README tells you to remove. The difference is architectural rather than cosmetic. Smart Composer is built as an editor-adjacent composer: you select context, you get a completion or an edit. YOLO is built as an agent runtime with retrieval, tool calling, MCP, subagents and a persistent memory system layered underneath the same chat surface. If you want a fast inline writing aid and nothing else, the composer model is lighter and has no conflict to resolve. If you want the assistant to search your vault, call tools and run multi-step tasks, the composer model is the wrong shape.

The second alternative is not a plugin at all: keep Obsidian as an editor and use a chat client with a file-sync or export step. That avoids the Smart Composer conflict, keeps keys out of the vault, and works the same on every platform. It also means your notes are stale the moment you edit them, and you lose Quick Ask, cursor chat and tab completion entirely. For someone who writes in Obsidian all day, that round trip is the cost YOLO is designed to remove.

A third comparison is the CLI agents themselves. If you already run Claude Code or Codex in a terminal, YOLO's CLI chat is a convenience wrapper around what you have, not a replacement. The README's claim is that you can use the CLI you are already signed into from inside Obsidian, which is a workflow argument, not a capability argument.

Licence, maintenance and what an upgrade costs

The repository is MIT licensed, which permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is the permissive end of the spectrum. It also means there is no warranty, and the licence text in the repository is the thing to read; this is a description of the licence, not legal advice.

The last push to the default branch was on 2026-08-27, and the most recent release, 1.6.6.2, carries the same timestamp. The repository is not archived. Releases 1.6.6, 1.6.6.1 and 1.6.6.2 all landed on 2026-08-24 or 2026-08-27, which indicates a patch cadence around a larger 1.6 line rather than a steady stream of small changes.

Upgrade cost is mostly configuration drift. The plugin stores model selection, API keys, knowledge base configuration and memory data. The README does not document a migration or rollback path for those settings, so an upgrade that changes how knowledge bases are indexed or how memory is stored could require re-indexing. The repository carries a versions.json and a version-bump.mjs, which is the standard Obsidian mechanism for declaring which plugin versions are compatible with which minimum app versions. Check that file before jumping versions rather than assuming the newest tag is safe for your Obsidian build.

Editorial conclusion

Adopt YOLO if you already live in Obsidian, want retrieval grounded in your own notes, and are willing to put API keys or OAuth credentials into plugin settings. Skip it if you only want a single inline completion engine, if you rely on Smart Composer, or if you need a support contract. Before installing, check the latest release tag against the manifest version, confirm that Smart Composer is disabled, and decide whether the on-device embedding path is enough or whether you will pay for an embedding API.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes