Getting Started
===============

Installation
------------

Install from PyPI:

.. code-block:: bash

   pip install folderbot

Or install from source:

.. code-block:: bash

   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:

.. code-block:: bash

   cd /path/to/your/folder

2. Run the interactive setup wizard:

.. code-block:: bash

   folderbot init

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

- Your Telegram bot token (from `@BotFather <https://t.me/BotFather>`_)
- Your LLM API key (Anthropic, OpenAI, etc.)
- Your Telegram user ID (from `@userinfobot <https://t.me/userinfobot>`_)

The root folder is automatically set to your current directory.

3. Start the bot:

.. code-block:: bash

   folderbot run

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

.. code-block:: bash

   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 :doc:`cli` for the full service management reference.