Claw Drive

Claw Drive

Organize and retrieve personal files with auto-categorization and a searchable index.

⚠️ Privacy — Read This First

File contents are personal data. Treat them accordingly.

• NEVER read file contents without explicit user consent. Always ask first. Always.
• If the user doesn't reply → default to SENSITIVE. Silence = no consent.
• identity/ files are ALWAYS sensitive — never read, never extract, never log contents.
• Extracted content enters the conversation transcript which is logged permanently to .jsonl files. Once you read a file, its contents are in the logs forever.
• Descriptions in INDEX.jsonl are also persistent. Don't put sensitive details (SSNs, account numbers, passwords) in descriptions even for non-sensitive files — use redacted/partial forms (e.g. "account ending ****4321").
• When in doubt, don't read. A vague index entry is better than leaked personal data.

Data locality: All data stays on your machine. INDEX.jsonl, stored files, and hash ledger are local. Conversation transcripts (.jsonl) are also local to your OpenClaw instance. Nothing is sent to external servers unless you explicitly enable Google Drive sync (optional, and only syncs the files you choose).

Dependencies

• claw-drive CLI — brew install dissaozw/tap/claw-drive (or make install from skill directory for manual setup)
• pymupdf — PDF text extraction (uv run --with pymupdf — no global install needed)
• rclone — Google Drive sync (optional): brew install rclone
• fswatch — file watch daemon (optional): brew install fswatch

⚠️ CLI Usage — Read This Before Running Anything

ALWAYS use the claw-drive CLI. NEVER use cp, mv, or direct file writes to ~/claw-drive/.

The CLI handles copying, hashing, deduplication, and index updates atomically. Bypassing it causes:

• Files stored without hash registration → dedup breaks silently
• INDEX.jsonl out of sync with actual files
• Version confusion when replacing files

PATH note: If installed via Homebrew (brew install dissaozw/tap/claw-drive), the binary is in /opt/homebrew/bin/ and should be in PATH automatically. If installed manually, ~/.local/bin may not be in the agent shell's PATH — use the full path:

claw-drive store ...

If the manual symlink is broken, re-run make install from ~/.openclaw/skills/claw-drive/ to fix it.

Setup

claw-drive init [path]

This creates the directory structure, INDEX.jsonl, and hash ledger. Default path: ~/claw-drive.

Workflow

Storing a file

When receiving a file (email attachment, Telegram upload, etc.):

1. Privacy check — ask the user gracefully if the file contains sensitive/personal data:

   • Something like: "Should I read the contents to index it better, or would you prefer I keep it private and just use the filename?"
   • If user says sensitive, or if user doesn't reply → treat as sensitive (default-safe)
   • If user confirms it's fine to read → proceed with full extraction
   • Files going to identity/ are always sensitive — never read contents
   • Sensitive flow: classify by filename/metadata only. If that's not enough for a good description, ask the user for a brief description. Never read file contents into the conversation.

2. Extract (normal files only) — read file contents:

   • PDFs: extract text via uv run --with pymupdf python3 -c "import pymupdf; ..." or use the image tool
   • Images: use the image tool to read/describe contents
   • Other formats: read directly if possible
   • Pull out key entities: names, dates, amounts, account/policy numbers, addresses, etc.

3. Classify — determine the best category from the categories table below

4. Inspect category structure — after choosing a category, examine existing subfolders in that category (e.g. with tree/find) before finalizing destination

5. Choose destination path

   • If an existing subfolder is a clear semantic match, store there
   • If multiple existing subfolders could match (conflicting/ambiguous), store at category root
   • Store at category root when the file is only generally related to the category and lacks specific detail
   • Create a new subfolder only when no existing subfolder fits and the file has clear specific detail that justifies one

6. Name — choose a descriptive filename: <subject>-<detail>-<YYYY-MM-DD>.<ext>

7. Describe — write a rich description using extracted content (or user-provided description for sensitive files). Include key details (dates, amounts, IDs, names) so the file is findable by any relevant search term. Don't be vague — "insurance card" is bad, "Acme Insurance ID cards - 2024 Honda Civic, Policy ****3441, effective 1/21/2026–7/21/2026" is good.

8. Tag — include specific tags from extracted content (model names, policy numbers, VINs, entity names) in addition to category tags

9. Store — run the CLI (use full path if claw-drive not in PATH):

   claw-drive store <file> --category <cat> --name 'clean-name.ext' --desc 'Rich description with key details' --tags 'tag1, tag2' --source telegram

   • Shell quoting safety: Prefer single quotes for --desc/--tags/--name when constructing shell commands. This avoids $ expansion (e.g. currency amounts like $941.39) and prevents metadata corruption. ⚠️ Do NOT use cp or write files directly to ~/claw-drive/. The CLI is the only correct way to store files — it handles copying, hashing, dedup, and index updates atomically.

10. Report — tell the user: path, category, tags, key extracted details, and what was indexed

The CLI handles copying, hashing, deduplication, and index updates automatically. If the file is a duplicate, it will be rejected.

The --name flag lets you override the original filename (which may be ugly like file_17---8c1ee63d-...) with a clean, descriptive name.

Retrieving a file

Do NOT read INDEX.jsonl directly in the main session. Spawn a search sub-agent instead. This keeps the index out of your context window and scales to large file collections.

Why sub-agent?

The index grows with every stored file (~300 bytes/entry). At 1000+ files, reading the full index into the main agent's context wastes tokens and may hit context limits. A sub-agent runs in its own isolated session with a cheap model, reads the index, and returns only the matching entries.

How to spawn

Use sessions_spawn with:

• mode: run
• model: A lightweight model is recommended (the search task is simple). Resolution order:
  1. Explicit model param on sessions_spawn (if provided)
  2. agents.defaults.subagents.model in config (if set)
  3. Falls back to the main agent's model
• task: The prompt below, with the user's query filled in

You are a file search agent. Read ~/claw-drive/INDEX.jsonl and find entries matching this query:

"<USER_QUERY>"

Return ONLY valid JSON, no explanation:

{
  "matches": [
    {
      "path": "<path from index>",
      "desc": "<desc from index>",
      "date": "<date from index>",
      "tags": ["<tags from index>"],
      "confidence": "high|medium|low"
    }
  ],
  "total_indexed": <number of entries in index>,
  "query": "<original query>"
}

Rules:
- Max 5 matches, sorted by relevance
- confidence: high = exact match, medium = likely relevant, low = tangential
- If no matches, return {"matches": [], "total_indexed": N, "query": "..."}
- Only read INDEX.jsonl, never read file contents

Receive and deliver

1. The sub-agent auto-announces its result back to your session
2. Parse the JSON from the announce message
3. Prepend ~/claw-drive/ to each path to get the full file path
4. Send the file: The claw-drive directory may not be in the message tool's allowed paths. If sending fails with "not under an allowed directory", copy the file to a temp location first (e.g. workspace), send it, then clean up:

   cp ~/claw-drive/<path> ~/.openclaw/workspace/
   # send via message tool
   rm ~/.openclaw/workspace/<filename>

5. Never show raw sub-agent JSON to the user. The announce message is internal — immediately process it and deliver the file. The user should only see the file and a brief description, not search internals.
6. For multiple matches, send the most relevant one and list the rest — let the user pick