folderbot 0.1.18

Telegram bot for chatting with your folder using Claude AI

Folderbot

A Telegram bot that lets you chat with your folder using Claude AI.

Repository: https://gitlab.com/jorgeecardona/folderbot

Features

• Tool Use: Claude actively interacts with your files using built-in tools
• Built-in Tools: List, read, search, and write files
• Custom Tools: Extend with your own tools via .folderbot/tools.py
• Persistent Sessions: Conversation history stored in SQLite
• Auto-logging: All conversations logged to markdown files
• Access Control: Whitelist specific Telegram user IDs
• Append Protection: Configure which files can be appended to
• Smart Message Handling: Send multiple messages quickly - they're combined into one request
• Version Notifications: Get notified when the bot updates

Installation

pip install folderbot

Or install from source:

git clone https://gitlab.com/jorgeecardona/folderbot
cd folderbot
pip install -e .

Quick Start

# Initialize configuration
folderbot init

# Run the bot
folderbot run

Configuration

Configuration is stored in ~/.config/folderbot/config.yaml:

telegram_token: "YOUR_TELEGRAM_BOT_TOKEN"
anthropic_api_key: "YOUR_ANTHROPIC_API_KEY"
allowed_user_ids:
  - 123456789  # Your Telegram user ID

root_folder: /path/to/your/folder

read_rules:
  include:
    - "**/*.md"
    - "**/*.txt"
  exclude:
    - "**/docs/**"
    - ".git/**"
  append_allowed:
    - "logs/*.md"
    - "**/todo.md"

auto_log_folder: logs/
model: claude-sonnet-4-20250514

Get your Telegram user ID from @userinfobot.

Built-in Tools

Claude has access to these tools for interacting with your folder:

Tool	Description
list_files	List files in a folder or subfolder
read_file	Read the contents of a specific file
read_files	Read multiple files at once (concatenated view)
search_files	Search for text across all files
write_file	Create or update files (supports append mode)

All tools respect the include, exclude, and append_allowed patterns in your config.

Custom Tools

You can extend folderbot with custom tools by creating .folderbot/tools.py in your root folder.

Example: Daily Journal Tool

This example adds a tool that appends timestamped entries to a daily journal file:

# .folderbot/tools.py
from datetime import datetime
from pathlib import Path
from typing import Any

from pydantic import BaseModel, Field

from folderbot.tools import ToolDefinition, ToolResult


class JournalEntryInput(BaseModel):
    """Input for adding a journal entry."""
    content: str = Field(description="The journal entry content")
    mood: str = Field(default="neutral", description="Current mood (happy, sad, neutral, excited)")


class CustomTools:
    """Custom tools for my second brain."""

    def __init__(self, root_folder: Path):
        self.root_folder = root_folder

    def get_tool_definitions(self) -> list[dict[str, Any]]:
        tools = [
            ToolDefinition(
                name="add_journal_entry",
                description="Add a timestamped entry to today's journal with optional mood tracking",
                input_model=JournalEntryInput,
            ),
        ]
        return [t.to_api_format() for t in tools]

    def execute(self, tool_name: str, tool_input: dict[str, Any]) -> ToolResult:
        if tool_name == "add_journal_entry":
            return self._add_journal_entry(tool_input)
        return ToolResult(content=f"Unknown tool: {tool_name}", is_error=True)

    def _add_journal_entry(self, tool_input: dict[str, Any]) -> ToolResult:
        params = JournalEntryInput(**tool_input)

        # Create journal folder if needed
        journal_dir = self.root_folder / "journal"
        journal_dir.mkdir(exist_ok=True)

        # Today's journal file
        today = datetime.now().strftime("%Y-%m-%d")
        journal_file = journal_dir / f"{today}.md"

        # Create header if new file
        if not journal_file.exists():
            header = f"# Journal - {today}\n\n"
            journal_file.write_text(header)

        # Append entry with timestamp
        timestamp = datetime.now().strftime("%H:%M")
        mood_emoji = {"happy": "😊", "sad": "😢", "neutral": "😐", "excited": "🎉"}.get(params.mood, "📝")
        entry = f"### {timestamp} {mood_emoji}\n\n{params.content}\n\n---\n\n"

        with open(journal_file, "a") as f:
            f.write(entry)

        return ToolResult(content=f"Added journal entry to {today}.md")

Now you can tell the bot: "Add to my journal: Had a great meeting with the team today" and it will create a timestamped entry.

Alternative: Factory Function

Instead of a CustomTools class, you can export a create_tools(root_folder) function:

def create_tools(root_folder: Path):
    return CustomTools(root_folder)

Package Structure

For more complex tools, use .folderbot/tools/__init__.py:

.folderbot/
└── tools/
    ├── __init__.py      # Exports CustomTools or create_tools
    ├── journal.py       # Journal tool implementation
    └── reminders.py     # Reminder tool implementation

CLI Commands

Bot Management

folderbot run              # Run the bot
folderbot run --bot mybot  # Run a specific bot (multi-bot config)
folderbot status           # Show configuration status

Configuration

folderbot init                           # Interactive setup
folderbot config show                    # Show current config
folderbot config set telegram_token XXX  # Set a config value
folderbot config folder /path/to/folder  # Set root folder

Systemd Service

folderbot service install   # Install as user service
folderbot service enable    # Enable auto-start
folderbot service start     # Start the service
folderbot service stop      # Stop the service
folderbot service status    # Check service status
folderbot service logs      # View logs
folderbot service logs -f   # Follow logs
folderbot service uninstall # Remove service

Telegram Commands

Command	Description
/start	Initialize bot and show help
/clear	Clear conversation history
/new	Start a new topic (clears history)
/status	Show session info
/files	List files available in context

Multi-Bot Configuration

Run multiple bots with different folders from a single config:

anthropic_api_key: "SHARED_KEY"

bots:
  work:
    telegram_token: "WORK_BOT_TOKEN"
    root_folder: ~/work/notes
    allowed_user_ids: [123456789]

  personal:
    telegram_token: "PERSONAL_BOT_TOKEN"
    root_folder: ~/personal/notes
    allowed_user_ids: [123456789]

folderbot run --bot work
folderbot run --bot personal

Development

# Setup
./setup/setup.sh
source .venv/bin/activate

# Run tests
pytest

# Run with coverage
pytest --cov=folderbot

License

MIT