# File Inbox

> 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.

- Skill: `knownasnaffy/file-inbox-3` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add knownasnaffy/file-inbox-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/knownasnaffy/file-inbox-3/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: knownasnaffy (https://skillmd.com/u/knownasnaffy)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/knownasnaffy/file-inbox-3

---


# 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
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:
   ```bash
   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:
   ```bash
   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](references/tagging-guide.md).

## File Search & Retrieval

```bash
# 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

```markdown
# 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

```bash
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](references/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.