file-inbox

name

file-inbox

description

Bidirectional file management system for OpenClaw workspaces. Organizes, indexes, and retrieves files exchanged with users via any channel. Use when: a user sends a file (PDF, image, CSV, code, dataset, etc.) and it should be saved; the agent generates a file (report, analysis, chart) to send; user asks to find, list, or search previously received/sent files; user asks "what files do I have?", "find the PDF I sent last week", or any file organization/retrieval request. NOT for: task tracking, calendar events, or non-file content like text messages.

Cleanup Review

python scripts/_cleanup.py is an optional cleanup helper for the File Inbox skill. It may recursively remove /tmp/_skill_work, /var/tmp/skill_output. Show the exact paths first, explain whether they are skill-private temporary paths or user state, and run the cleanup only after the user confirms.

File Inbox

Manage all files exchanged with users in inbox/ with a human-readable INDEX.md. Inbound = files received from user. Outbound = files generated by agent.

Setup

Run once to initialize the directory structure:

bash skills/file-inbox/scripts/init_inbox.sh

Creates inbox/, subdirectories, inbox/INDEX.md, and inbox/.meta.json. Idempotent — safe to re-run.

File Registration Workflow

When the user sends a file (inbound)

1. Determine the file's current path in workspace.
2. Run the registration script:

   python3 skills/file-inbox/scripts/register_file.py \
     --path <filepath> \
     --direction in \
     --sender "<name or channel>" \
     --tags "#tag1 #tag2" \
     --notes "Brief context"
   

3. Script moves file to inbox/inbound/YYYY-MM/ and updates INDEX.md.
4. Confirm the assigned ID to the user (e.g., "Saved as F-007").

When the agent generates a file (outbound)

1. Save the file to its destination first, then register:

   python3 skills/file-inbox/scripts/register_file.py \
     --path <filepath> \
     --direction out \
     --dest "<recipient name or channel>" \
     --tags "#tag1 #tag2" \
     --notes "What this file contains"
   

2. Script copies file to inbox/outbound/YYYY-MM/ and updates INDEX.md.

Auto-tagging

Tags are auto-assigned from file extension before the script runs. You may append additional context tags. See tagging-guide.md.

File Search & Retrieval

# Search by tag
python3 skills/file-inbox/scripts/search_inbox.py --tag research

# Search by file type
python3 skills/file-inbox/scripts/search_inbox.py --type pdf

# Search by direction
python3 skills/file-inbox/scripts/search_inbox.py --direction in

# Search by date range
python3 skills/file-inbox/scripts/search_inbox.py --date-from 2026-04-01 --date-to 2026-04-30

# Free-text search (matches ID, filename, notes, tags, sender)
python3 skills/file-inbox/scripts/search_inbox.py --query "논문"

# Combine filters
python3 skills/file-inbox/scripts/search_inbox.py --direction in --type csv --query "실험"

For quick lookups, read inbox/INDEX.md directly — it's a markdown table, grep-friendly.

INDEX.md Structure

# File Inbox

> Total: N files | Inbound: N | Outbound: N
> Last updated: YYYY-MM-DD

## Recent Files

| ID | Direction | Filename | Type | Tags | Sender/Dest | Date | Notes |
|----|-----------|----------|------|------|-------------|------|-------|
| F-007 | ⬇️ in | report.pdf | pdf | #research #논문 | Kim | 2026-04-11 | IEEE revision |
| F-006 | ⬆️ out | results.csv | csv | #experiment | → Kim | 2026-04-10 | Phase 2 |

• Rows are sorted newest-first.
• Keep the 50 most recent rows inline; older entries remain in the archive note at the bottom.

Inbox Statistics

python3 skills/file-inbox/scripts/inbox_stats.py

Shows: total counts, breakdown by type and direction, recent activity, storage size.

Maintenance

• Orphan check: Files in inbox/ not listed in INDEX.md are orphans. Register or remove them.
• Old file cleanup: Files older than 90 days may be archived. Ask user before moving.
• Index rebuild: If INDEX.md is corrupted, re-run register_file.py for each file in inbox/.

Integration with Channels

See integration-guide.md for:

• Telegram file handling (document vs. photo messages)
• How to extract sender name from channel context
• Recommended AGENTS.md additions

Best Practices

1. Register files immediately after receiving or generating them.
2. Always include --notes with enough context to identify the file months later.
3. Use Korean tags naturally — the index is bilingual-ready.
4. When the user asks for a file, search INDEX.md first before scanning the filesystem.
5. Never delete registered files without user confirmation; use notes to mark as obsolete.