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

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.