vault-optimizer — Claude Code subagent: Obsidian vault cleanup
A Claude subagent that tunes Obsidian vault performance: finds oversized files, sorts out attachments and speeds up search.
npx claude-code-templates@latest --agent obsidian-ops-team/vault-optimizerWhat vault-optimizer does
vault-optimizer is a Claude subagent built for Obsidian vault performance. It watches load times and search response, flags markdown files over 1MB, breaks storage usage down by content type, and tells you what to do about it.
Five areas are covered: performance analysis, file size optimization, attachment handling, search indexing, and storage cleanup. The agent compresses images and PDFs, removes orphaned attachments, consolidates duplicates, archives old notes and templates. It runs find against the vault, so point it at the right path. The report includes a storage breakdown, the bottlenecks it found, and before/after metrics.
Back up first. The agent writes and moves files, and moving them is how note links break. It also carries target numbers: markdown capped at 1MB, JPEGs compressed to 85% quality, archiving for files older than 2 years. The age threshold is configurable; treat the rest as guidance rather than a hard rule. Its toolset is Read, Write, Bash, Glob, LS.
What it helps with
- find markdown files over 1MB that slow the vault down
- compress heavy images and PDFs without wrecking readability
- clear out orphaned attachments and duplicate notes
- sort attachments into folders instead of one dumping ground
- compare metrics before and after optimization
Example prompts for the agent
- analyze my Obsidian vault performance and show me what's slowing it down
- find files over 1MB in the vault and suggest what to compress
- clean up orphaned attachments, but back up first
How to install vault-optimizer
1claude-code-templates
npx claude-code-templates@latest --agent obsidian-ops-team/vault-optimizer2Manually: put the files in place
.claude/agents/vault-optimizer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/vault-optimizer.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/vault-optimizer.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about vault-optimizer
How do I install vault-optimizer in Claude?
Run npx claude-code-templates@latest --agent obsidian-ops-team/vault-optimizer, then check that the agent file sits at .claude/agents/vault-optimizer.md.
What does vault-optimizer do?
It keeps an Obsidian vault in shape: finds large files, compresses attachments, removes duplicates and junk, and looks at search indexing and startup time.
Which tools does the agent have?
It gets Read, Write, Bash, Glob and LS. File searches go through Bash, so the vault path has to be correct.
