AI Vault Inspector for Obsidian (Full Demo)
- 24/01/2026
Description
This video demonstrates an “AI Vault Inspector” agent built for Obsidian vaults, designed to combat maintenance chaos. The agent, powered by AI tools like Claude Code, scans notes to identify issues like missing metadata, broken tags, and inconsistent formatting, providing a prioritized health report with time estimates for fixes. It showcases both an inspection mode for diagnosis and a guided modification process, highlighting how custom AI agents and skills can revolutionize Obsidian vault management.
Best Ideas
1. AI-Powered Vault Health Reports: The core idea of using an AI agent to scan an Obsidian vault and generate a comprehensive, prioritized health report (critical, warnings, suggestions) with time estimates for fixes.
2. Inspection vs. Modification Mode with Granular Control: The crucial safety feature of first running an “inspection mode only” report, then allowing for guided, granular modifications with before-and-after previews and user approval for each individual change.
3. Universal AI Agent System (`agents.md`): Developing a central `agents.md` file at the vault root that defines the vault structure, conventions, and maintenance tasks, making the AI agent system compatible with multiple AI tools (Claude Code, Antigravity, Gemini CLI, OpenCode).
4. Obsidian “Skills” (`skill.md`): Teaching AI tools specific Obsidian functionalities (e.g., how to construct and edit a `.canvas` file) through dedicated `skill.md` files, enabling the AI to interact intelligently with complex Obsidian features beyond basic text editing.
5. Iterative Maintenance & Comprehensive Logging: The concept of running “quick win sessions,” logging all changes made by the AI in a `Verification Log`, and generating future prompts to continue maintenance work, ensuring a systematic, auditable, and easily resumable approach.
6. Proactive Problem Identification at Scale: The agent’s ability to quickly identify diverse issues across hundreds of files, such as missing YAML properties, inconsistent property naming, orphaned notes, mixed date formats, and file naming inconsistencies—problems that would be tedious or impossible to spot manually.
7. Customization and Adaptability for Personal Vaults: The emphasis that while the system is powerful, users will need to adapt the agent’s rules and instructions to their specific vault conventions and workflows, encouraging experimentation and personalization.
Tools and Resources
- AI Tools & Platforms:
- Claude Code: The primary AI tool used for demonstrations, available on a paid pro plan ($20 USD/month).
- Google Antigravity: An IDE (fork of VS Code) that integrates Google’s AI models (Gemini); offers a generous free tier with limits, then requires a Google AI Pro/Ultra subscription.
- Google Gemini CLI: A command-line interface for Google’s Gemini AI, described as a free way to get started.
- OpenCode: An open-source AI coding agent; free to use but requires users to provide their own API key (which can incur costs).
- Google AI Studio: Used for obtaining Gemini API keys and tracking usage (`aisudio.google.com`).
- Anthropic API: The underlying API for Claude Code.
- Ultimate AI: An API aggregator that allows using agents and skills inside Obsidian with IDEs for $7 USD/month (`chat.ocidianai.tools.com`).
- Integrated Development Environments (IDEs):
- VS Code (Visual Studio Code): The creator’s preferred IDE due to extension availability.
- Antigravity IDE: A new IDE that is a fork of VS Code, specifically for Google’s AI models.
- Obsidian Specifics:
- Obsidian Vaults: The personal knowledge management system that the AI agent inspects and maintains.
- Obsidian Canvas: A specific Obsidian feature demonstrated where AI skills can be applied (creating/editing `.canvas` files).
- YAML Front Matter: A common method for adding metadata to Obsidian notes, frequently checked by the inspector.
- Key Files & Folder Structures:
- `agents.md`: A comprehensive reference file at the vault root for all AI agents, explaining vault structure and maintenance tasks, making the system universal across AI tools.
- `skill.md` files (e.g., `obsidian-json-canvas.md`): Specific files located in a `.claude-skills` folder (or similar) that teach the AI how to interact with particular Obsidian features or file types.
- `verification-log.md`: An audit trail file that logs all operations and changes made by the AI agent.
- `claude-nick.md`: A general vault context file that provides AI tools with an overview of the vault’s structure and conventions.
- `README.md`: A user-friendly getting started guide for the AI agent system.
- Technical Prerequisites for IDEs: Git, Node.js, Python.
- Community Resources:
- Capano’s Obsidian Skills: Mentioned as an inspiration and source for learning about `skill.md` files (found on GitHub and trending on Reddit).
- Creator’s Content Platforms: Co-Fire and Paul’s Vault Members Perks (where the full system files are shared).
Key Learning Points
1. Automate Obsidian Maintenance with AI: AI agents can effectively streamline and automate the tedious tasks of maintaining an Obsidian vault, identifying inconsistencies, missing metadata, and structural issues far more efficiently than manual checks.
2. Structure AI Instructions for Precision: To get valuable results from AI, it’s essential to provide clear and structured instructions through dedicated configuration files (`agents.md`, `skill.md`) that detail the vault’s conventions and specific application functionalities.
3. Prioritize Safety with AI-Driven Modifications: Always use AI tools cautiously, starting with “inspection-only” modes, reviewing proposed changes meticulously with “before-and-after” comparisons, and always maintaining a full backup of your vault before allowing AI to make significant modifications.
4. Leverage Obsidian’s File-Based Nature: Obsidian’s architecture, storing notes as plain text files, is a major advantage, allowing external AI tools and IDEs to directly access, analyze, and modify the vault content programmatically.
5. Understand AI Tool Capabilities & Costs: Different AI tools offer varying levels of functionality, integration, and cost. Users should experiment to find the tool (or combination of tools) that best fits their technical comfort, budget, and specific maintenance needs.