turbovault: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

TurboVault is an MCP (Model Context Protocol) server that gives AI agents safe, fast access to Obsidian vaults. It's written in Rust and exposes 52 tools (30 listed by default, 22 advanced ones on request), note resources, workflow prompts and completions, for reading, writing, searching, analyzing and managing notes.

Key design principle: built on the TurboMCP framework (3.x; the exact version is in the workspace Cargo.toml), which provides typed tool definitions, transports, auth and telemetry. TurboVault adds the vault: write safety, an index that can't miss an outside edit, and the tools on top.

Development Commands

Build and test

just build            # cargo build
just release          # cargo build --release (fat LTO)
just test             # fmt-check, lint, test-all
just test-quick       # tests only
just test-one module::test_name

cargo test --workspace --all-features
cargo test --workspace --tests     # integration tests only
cargo test --workspace --lib       # unit tests only

Code quality

cargo fmt --all
cargo clippy --workspace --all-features --all-targets -- -D warnings
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
cargo machete                      # unused dependencies (CI runs it)
cargo deny check && cargo audit --deny warnings

CI runs clippy on current stable; a newer clippy can flag code an older one passed, so keep the local toolchain current (rustup update stable).

Snapshots, properties, fuzzing, benchmarks

# The tool catalog snapshot (names, descriptions, input and output schemas).
# Re-bless after changing any tool, then review the diff.
UPDATE_TOOL_CATALOG=1 cargo test -p turbovault --lib

# The parser contract snapshot.
UPDATE_PARSER_SNAPSHOT=1 cargo test -p turbovault-parser --test test_contract_snapshot

# Property tests run with the normal suite; raise the case count to dig.
PROPTEST_CASES=4096 cargo test -p turbovault-tools --test proptest_rewriter

# Fuzz targets (nightly, outside the workspace): parse_note, parse_blocks,
# frontmatter, edit_blocks, rewrite_links.
cd fuzz && cargo +nightly fuzz run parse_note -- -max_total_time=60

# Benchmarks, including a 10,000-note vault.
cargo bench -p turbovault --bench vault_10k
cargo bench -p turbovault-git --bench vault_size