Website · Documentation · Live Demo · Report Bug · Request Feature

---

Browse files by meaning, not folders.

What is ClawDrive?

ClawDrive indexes your files (text, images, audio, video) and makes them searchable by meaning. You interact with it through a CLI, a REST API, or a browser UI with a 3D file cloud.

Files live in pots. A pot is a named collection you build from files, folders, or URLs. Search and sharing are both scoped to the pot — nothing else on your machine is visible.

Everything runs on your machine. The only external call is to Gemini for embeddings. For remote access, point a tunnel at the local server.

Features

• Multimodal Shared Representation: Text, images, audio, and video all live in the same embedding space.
• Cross-Modal Retrieval: Search your files by meaning—use text to find images, or images to find text.
• Bring-Your-Own Transcriber: Attach transcripts (e.g., from WhisperX) directly to audio and video files for deep indexing.
• Tiered Retrieval System: Save LLM context windows. ClawDrive returns a 1-sentence tldr or a markdown digest before you fetch the full file.
• 3D Visualization & Web UI: Browse your files spatially with an interactive 3D frontend.
• Pot-Based Local Sharing: Group files into isolated "pots". Share contexts directly peer-to-peer via local tunnels (Tailscale, Cloudflare).
• Auto File Naming & Organization: Import everything cleanly without UUIDs; duplicates are automatically suffixed and organized.

Quick Start

# Install globally (requires ffmpeg for audio/video: brew install ffmpeg)
npm install -g clawdrive

# Set your Gemini API key
export GEMINI_API_KEY="your-key-here"

# Launch the web UI with a curated NASA demo (~248 MB on first run)
cdrive serve --demo nasa

# For a read-only hosted demo, add --read-only
cdrive serve --demo nasa --read-only

The npm package is clawdrive; the installed CLI command is cdrive.

Or run directly without installing:

npx --package clawdrive cdrive serve --demo nasa

Prefer the hosted version? Try the live demo at app.claw3drive.com.

Get a free Gemini API key at aistudio.google.com/apikey

Configuration

ClawDrive reads settings from the environment and from ~/.clawdrive/config.json:

{
  "gemini_api_key": "your-key-here",   // alternative to GEMINI_API_KEY env var
  "default_workspace": "default",
  "embedding": {
    "model": "gemini-embedding-2-preview",
    "dimensions": 3072
  }
}

The GEMINI_API_KEY environment variable takes precedence over the config file. Data is stored in ~/.clawdrive/workspaces/.

Pots and sharing

A pot can be anything — a specific codebase, a side-project workspace, or a feature's design docs. All search and sharing happens at the pot level, so you never accidentally expose files outside of it.

For remote access, put a tunnel in front of the local server (Tailscale, Cloudflare, etc.) — see tunnels guide for options. Storage stays on your machine.

Ingest pipeline

When you add files to a pot, ClawDrive turns them into something agents can actually search. Text gets chunked and summarized, audio and video get transcribed, and images become part of the same index.

Supported formats: PDF, Markdown, TXT, JSON, JPG, PNG, GIF, WebP, SVG, MP4, MOV, WebM, MP3, WAV.

Tiered retrieval

Agents don't need to read an entire file to decide if it's relevant. ClawDrive returns a one-line tldr with every search hit, a longer digest on request, and the full original only when you actually need it.

CLI quick reference

Command	Description
cdrive pot create <name>	Create a pot for a project, dataset, or working set.
cdrive add --pot <pot> <sources...>	Import files, folders, or URLs into a pot.
cdrive search [query] --pot <pot>	Search by meaning, scoped to one pot when you want it.
cdrive search --file <path>	Use an image, PDF, audio, or video file as the query.
cdrive get <file-or-share>	Read a file by canonical name, or inspect a share by id or token.
cdrive pot list	List all pots with file counts.
cdrive pot delete <pot>	Delete a pot (files are untagged, not removed).
cdrive todo [--pot <pot>] [--kind <kinds>]	Find files still missing agent-written metadata such as tldr, digest, or transcript.
cdrive tldr <file>	Show or update the short summary attached to a file.
cdrive share pot <pot> --to <principal>	Create a pot-scoped share for a person or agent.
cdrive share pot <pot> --link	Create a pending link share you can approve and send out.
cdrive install-skill [--agent <name>]	Install the bundled ClawDrive skill for Claude Code, Copilot, or Codex.
cdrive doctor	Check the local workspace for configuration or health issues.
cdrive serve [--demo nasa]	Start the local API and 3D web UI, optionally in demo mode.

Full command reference: CLI.md · REST API runs on the same port (/api/*)

Every command also supports --json:

$ cdrive search "launch telemetry" --json

[
  {
    "id": "file_01...",
    "file": "apollo-11-transcript.pdf",
    "contentType": "application/pdf",
    "tldr": "Full transcript of Apollo 11 comms...",
    "score": 0.94
  }
]

Community

Join the Discord to ask questions, share what you're building, and follow development.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.

---

Built by Daniil & Matin in Berlin.