Getting Started

Installation

Install from PyPI:

pip install folderbot

Or install from source:

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

Quick Start

  1. Navigate to the folder you want the bot to manage:

cd /path/to/your/folder

  1. Run the interactive setup wizard:

folderbot init

This creates .folderbot/config.toml in your folder and prompts you for:

  • Your Telegram bot token (from @BotFather)

  • Your LLM API key (Anthropic, OpenAI, etc.)

  • Your Telegram user ID (from @userinfobot)

The root folder is automatically set to your current directory.

  1. Start the bot:

folderbot run

  1. Open Telegram and send a message to your bot. Try:

    • “What files are in my folder?”

    • “Read my todo.md”

    • “Search for anything mentioning ‘meeting’”

Features

  • Tool Use: The AI actively interacts with your files using built-in tools

  • Web Tools: Search the web and fetch content from URLs

  • Task Scheduler: Schedule long-running, repeating, cron, or time-limited tasks

  • File Notifications: Get alerted when files in your folder change

  • Activity Logging: View detailed logs of all tool calls and bot activity

  • Custom Tools: Extend with your own tools via .folderbot/tools.py

  • Persistent Sessions: Conversation history stored in SQLite

  • Voice Messages: Send voice messages – transcribed locally via faster-whisper

  • Access Control: Whitelist specific Telegram user IDs

  • Smart Message Handling: Send multiple messages quickly – they’re combined into one request

Running as a Service

Install Folderbot as a systemd user service for automatic startup:

folderbot service install
folderbot service enable
folderbot service start

This also installs an auto-update timer that checks PyPI for new versions every 5 minutes.

See CLI Reference for the full service management reference.