Obsidian Inbox Processor

A Streamlit-based tool for processing your Obsidian inbox with LLM-assisted summaries, intelligent tagging, and semantic note linking.

What It Does

This tool helps you process notes in your Obsidian inbox folder by:

• Analyzing content with LLMs to generate structured summaries
• Suggesting tags based on your existing vault taxonomy
• Finding related notes using semantic search (vector embeddings)
• Creating new notes from templates with generated content
• Appending to existing notes for incremental knowledge building

Perfect for processing Readwise exports, web clippings, or any inbox notes that need to be distilled into your permanent note system.

Features

• LLM-Powered Analysis: Uses OpenRouter to access various LLMs (Claude, GPT-4, etc.) for content summarization
• Semantic Search: ChromaDB-powered vector search finds related notes in your vault
• Tag Matching: Suggests tags that already exist in your vault for consistency
• Template Support: Inserts content at cursor markers (<% tp.file.cursor() %>) for Templater compatibility
• Multi-Pass Chunking: Handles long documents by chunking and synthesizing summaries
• Progress Tracking: Tracks processing stats (today, this week)
• Safe Deletion: Moves files to system trash instead of permanent deletion

Quick Start

Prerequisites

• Python 3.13+
• uv package manager
• An OpenRouter API key

Installation

# Clone the repository
git clone https://github.com/Cherubeam/obsidian-inbox-processor.git
cd obsidian-inbox-processor

# Install dependencies
uv sync

Configuration

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env with your settings:

   VAULT_PATH="/absolute/path/to/your/vault"
   OPENROUTER_API_KEY="your_openrouter_key"

See docs/configuration.md for all available options.

Running

uv run streamlit run src/obsidian_inbox_processor/ui/app.py

The app will open in your browser at http://localhost:8501.

Usage

1. Select an inbox item from the sidebar
2. Click "Analyze" to generate a summary with tags and related notes
3. Review and edit the generated content in the preview area
4. Choose an action:
   • Create Note: Create a new note from your template
   • Append to Note: Add content to an existing note
   • Delete: Move the inbox item to trash

First-Time Setup

Before using related notes, index your vault:

1. Click "Re-index vault" in the sidebar
2. Wait for the indexing to complete (progress shown)

Project Structure

src/obsidian_inbox_processor/
├── core/               # Business logic
│   ├── config.py           # Environment configuration
│   ├── actions.py          # File operations (create, append, trash)
│   ├── processor.py        # LLM prompt building and response parsing
│   ├── llm_clients.py      # OpenRouter API client wrappers
│   ├── retrieval.py        # Semantic search and ranking
│   ├── indexer.py          # Vault indexing with embeddings
│   ├── chunking.py         # Document chunking for long content
│   └── ...                 # Additional modules (see docs/architecture.md)
└── ui/                 # Streamlit interface
    ├── app.py              # Main application
    ├── sidebar.py          # Inbox selection
    ├── analysis_panel.py   # Analysis controls and preview
    ├── actions_panel.py    # Create/append actions
    └── delete_panel.py     # Delete confirmation dialog

Known Limitations

• Early Development: This is a personal tool being shared publicly. Expect rough edges.
• Template Format: Currently optimized for Templater-style cursor markers
• Single User: No multi-user support; designed for local use
• LLM Dependency: Quality of summaries depends on the chosen model and prompt

Troubleshooting

See docs/troubleshooting.md for common issues.

Common issues:

• "Embeddings not configured" → Check your OPENROUTER_API_KEY
• "No related notes" → Run "Re-index vault" first
• Tags not matching → Ensure tags exist in your vault notes

Contributing

Contributions are welcome! This project was built with Claude Code (Anthropic's CLI tool).

# Run tests
uv run pytest tests/ -v

# Run linting
uv run ruff check .

License

MIT License - see LICENSE for details.

Acknowledgments

• Built with Streamlit
• Vector search by ChromaDB
• LLM access via OpenRouter
• Developed with assistance from Claude Code