Codex Time Bot

Important

This repository is an educational demo MVP created for a YouTube tutorial. It is intentionally small and is not intended to be production-ready.

Watch the YouTube tutorial

The original video is in Ukrainian. English auto-dubbing is also available.

Tutorial, Demo & Related Project

• Read the tutorial: English | Українська
• Try the tutorial demo: @codex_time_bot
• Explore the full-featured production bot: @cryptocodi_bot | Source code

This repository contains the educational time-conversion MVP used in the tutorial. @codex_time_bot is its deployed demo, while @cryptocodi_bot is a larger production project with its complete source code available publicly.

Codex Time Bot is a Telegram bot that finds time and timezone expressions in messages and converts them between Kyiv, Central European, and UTC time.

Features

• Parses expressions with or without a space: 10:00 utc and 10:00utc.
• Finds time expressions inside longer text messages.
• Supports multiple unique expressions in one message.
• Converts every match in the fixed order: KYIV, CET, UTC.
• Uses timezone rules instead of fixed offsets:
  • UTC
  • Europe/Kyiv
  • Europe/Vienna for the MVP CET label
• Applies daylight-saving rules provided by Python zoneinfo.
• Ignores unsupported expressions and messages without matches.
• Replies directly to the original Telegram message.

Example response:

10:00 UTC ┬─> 13:00 KYIV
          ├─> 12:00 CET
          └─> 10:00 UTC

UTC — UTC (UTC+00:00)

Explicit offsets such as 10:00 UTC+2 are not supported in the MVP and are ignored.

Requirements

• Python 3.12
• A Telegram bot token

Local Setup

Clone the repository and enter the project directory:

git clone https://github.com/deKibi/codex-time-bot.git
cd codex-time-bot

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

Install production dependencies:

python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Create the local configuration file:

cp .env.example .env

Edit .env and replace the placeholder token:

TELEGRAM_BOT_TOKEN=replace_with_your_telegram_bot_token
MAX_TIME_MATCHES_PER_MESSAGE=5

MAX_TIME_MATCHES_PER_MESSAGE limits unique time and timezone pairs. Duplicate pairs do not count toward the limit.

Running the Bot

python main.py

The bot uses Telegram long polling. Send it a text message containing a supported time expression; messages without matches are ignored.

Tests

Install development dependencies:

python -m pip install -r requirements-dev.txt

Run all tests:

python -m pytest

Tests also run in GitHub Actions on Ubuntu 24.04 with Python 3.12.

Logging

Logs are written to both the console and logs/bot.log. File logs rotate daily, and the latest 30 rotated files are retained. Original Telegram message text and bot tokens are not logged.

Simple Deployment on Ubuntu 24.04

This demo deployment runs the bot inside a GNU screen session. It does not set up automatic restarts or other production infrastructure.

Install the required system packages:

sudo apt update
sudo apt install -y git python3 python3-venv screen

Clone and configure the project:

git clone https://github.com/deKibi/codex-time-bot.git
cd codex-time-bot
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env
nano .env

Start a named screen session:

screen -S codex-time-bot

Inside the session, activate the environment and start the bot:

source .venv/bin/activate
python main.py

Useful screen controls:

• Detach while keeping the bot running: press Ctrl+A, then D.
• Reconnect: screen -r codex-time-bot.
• Stop the bot after reconnecting: press Ctrl+C.