ragfs: Instructions file for Claude Code

CLAUDE.md

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

Build Commands

cargo build                          # Development build
cargo build --release                # Release build
cargo build -p <crate-name>          # Build specific crate

Testing

cargo test --all                     # Run all tests
cargo test -p <crate-name>           # Run tests for specific crate
cargo test -- --nocapture            # Run tests with output

Linting & Formatting

cargo fmt --all                      # Format code
cargo fmt --all -- --check           # Check formatting
cargo clippy --all-targets -- -D warnings  # Run clippy

Running

cargo run -- -v index /path/to/dir   # Index with verbose logging
cargo run -- query /path "search"    # Query the index
RUST_LOG=debug cargo run -- ...      # Debug logging

Architecture

RAGFS is a FUSE filesystem for semantic search using vector embeddings. It's organized as a Rust workspace with 9 crates following a pipeline pattern:

File → Extraction → Chunking → Embedding → Storage → Search

Crate hierarchy:

• ragfs - CLI binary (entry: crates/ragfs/src/main.rs)
• ragfs-core - Foundation traits and types (traits.rs, types.rs)
• ragfs-extract - Content extraction via ExtractorRegistry
• ragfs-chunker - Document chunking via ChunkerRegistry
• ragfs-embed - Local embeddings using Candle (gte-small, 384-dim)
• ragfs-store - Vector storage with LanceDB
• ragfs-index - Pipeline orchestration and file watching
• ragfs-query - Query execution
• ragfs-fuse - FUSE filesystem with agent operations, safety layer, and semantic features

ragfs-fuse modules:

• filesystem.rs - Main FUSE handler, inode management, virtual directory routing
• ops.rs - OpsManager for file operations with JSON feedback (.ops/)
• safety.rs - SafetyManager for soft delete, audit logging, undo (.safety/)
• semantic.rs - SemanticManager for AI-powered file operations (.semantic/)