LiveFolders: Instructions file for Claude Code

CLAUDE.md

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

Commands

# Build
cargo build
cargo build --release

# Run tests
cargo test

# Run a single test (by name substring)
cargo test <test_name>

# Run tests for a specific module
cargo test --lib config::tests

# Run with debug logging
RUST_LOG=livefolders=debug cargo run -- mount --foreground

# Cross-compile for aarch64 Linux (requires `cross`)
cross build --target aarch64-unknown-linux-gnu --release

Architecture

LiveFolders is a FUSE filesystem that exposes tools as plain files. LLMs interact with tools using cat and echo with no protocol or SDK.

Data flow

1. LLM writes to an endpoint file (e.g. echo "London" > .livefolders/tools/weather/forecast).
2. FUSE open() captures the caller's session id (via getsid(req.pid())) and binds it to a fresh file handle.
3. FUSE write() looks up the per-(inode, sid) invocation slot and appends bytes to its private write_buf.
4. FUSE release() fires when the fd closes. For write_invoke it marks the slot Pending and spawns the handler onto the Tokio runtime, returning immediately so the FUSE thread is free for other ops.
5. The handler runs as a shell command with input on stdin. On completion the spawned task stores the output in slot.result, transitions the slot to Ready, and wakes any awaiters via Notify::notify_waiters().
6. LLM reads the endpoint (cat .livefolders/tools/weather/forecast) — FUSE read() looks up the slot, awaits if Pending, slices slot.result[offset..] when Ready, and drops the slot once fully drained.
7. The slot's trace (duration_ms, exit status, stderr) is exposed via the <endpoint>.log companion file.

For read_invoke endpoints the handler is kicked by the first read() instead of by release(); the state machine is otherwise the same.

Concurrency model

• Invocation state is keyed by (inode, session id) so echo and cat from the same shell pipeline share a slot, while pipelines from different shells (different sids) run in parallel and never clobber each other.
• FUSE issues some operations (notably release and async read) with pid == 0; for those we look up the sid captured at open() time via the file handle (see fs::sid).
• Handlers run on the Tokio runtime, not on the FUSE dispatcher thread. Two slow handlers complete in ~max(t1, t2), not t1 + t2.
• state_file flock (declared in folder.yaml) is the only cross-tool isolation primitive. Handlers that share external state (a database, an API rate limit, a file) must either be idempotent or declare a state_file.
• Idle slots are reaped after 15 minutes by default (vfs::spawn_reaper) so abandoned opens cannot leak memory.