Fetchium CLAUDE.md

CLAUDE.md

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

Build Commands

# Check all crates compile (fast, no linking)
cargo check

# Build the fetchium binary
cargo build -p fetchium-cli

# Build optimized release binary
cargo build -p fetchium-cli --release

# Run the binary
./target/debug/fetchium --help
./target/debug/fetchium doctor

# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p fetchium-core
cargo test -p fetchium-cli

# Run a single test by name
cargo test -p fetchium-core extract::layer1::tests::extract_simple_page

# Lint (zero warnings policy — treat warnings as errors in CI)
cargo clippy -- -D warnings

# Format
cargo fmt

# Generate docs
cargo doc --open

macOS SDK Note

Xcode on this machine sometimes defaults to the iPhoneOS SDK, which breaks C dependency compilation (zstd-sys, rusqlite, ring). This is fixed in .cargo/config.toml which forces SDKROOT to the macOS SDK. If you see "architecture not supported" errors, run:

export SDKROOT=$(xcrun --sdk macosx --show-sdk-path)

Architecture Overview

Fetchium is a Cargo workspace with 4 crates:

Crate	Role
fetchium-core	All algorithms: search, extract, rank, validate, cache, AI, intelligence
fetchium-cli	The fetchium binary — clap derive CLI, delegates everything to fetchium-core
fetchium-mcp	MCP server (Phase 4) — exposes fetchium-core as Model Context Protocol tools
fetchium-api	REST API server via axum (Phase 4)

Data flow: CLI command → FetchiumConfig → fetchium-core pipeline → formatted output

The CLI (fetchium-cli/src/main.rs) parses args, loads config, then dispatches to one file per command in crates/fetchium-cli/src/commands/. Each command calls into fetchium-core modules.

fetchium-core Module Map

The retrieval pipeline is implemented across these modules. Foundational types/config:

• types.rs — Shared data types: AgentSearchResult, SearchResult, ResultItem, Segment, Finding, Source, EvidenceGraph, CepLayer, PdsTier, ResourceTier, BackendId, etc.
• error.rs — FetchiumError, StructuredError, ErrorKind, FetchiumResult<T>
• config.rs — FetchiumConfig loaded from ~/.fetchium/config.toml with env var overrides; includes detect_resource_tier() and data_dir()
• http/client.rs — HttpClient (reqwest with pooling/retries)
• resource/mod.rs — detect_tier() delegating to FetchiumConfig::detect_resource_tier()