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.

Deployment on Ubuntu 24.04

Simple screen run

This option runs the bot manually inside a GNU screen session under a regular Linux user. It is simple and lets you reconnect to the bot session, but it does not start the bot automatically after a server reboot.

Install the required system packages:

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

Clone and configure the project in the regular user's home directory:

cd ~
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

Check the project path. This is only an example path to the cloned GitHub repository; replace it with the actual path on your server where needed:

pwd
# Example output:
# /home/denys/codex-time-bot

Start a named screen session:

screen -S codex-time-bot

Inside the screen session, 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 to the bot session: screen -r codex-time-bot.
• List sessions: screen -ls.
• Stop the bot after reconnecting: press Ctrl+C.

Run as a systemd service

Use this option when the bot should start together with the system and restart after crashes.

First complete the clone and configuration setup from the simple screen run section above. Then create a systemd service file:

sudo nano /etc/systemd/system/codex-time-bot.service

Example service configuration:

[Unit]
Description=Codex Time Bot
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=denys
WorkingDirectory=/home/denys/codex-time-bot
Environment=PYTHONUNBUFFERED=1
ExecStart=/home/denys/codex-time-bot/.venv/bin/python main.py
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

In this example, denys is the regular Linux user that runs the bot, and /home/denys/codex-time-bot is only an example project path. Replace User, WorkingDirectory, and the path in ExecStart with your actual values.

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable codex-time-bot
sudo systemctl start codex-time-bot

Check service status:

sudo systemctl status codex-time-bot

If the bot runs as a systemd service, make sure it is not also running in a parallel screen session to avoid running two bot instances at the same time. List existing screen sessions with:

screen -ls

Useful service commands:

sudo systemctl stop codex-time-bot
sudo systemctl restart codex-time-bot

Useful autostart commands:

sudo systemctl enable codex-time-bot
sudo systemctl disable codex-time-bot

• Enable autostart after reboot: sudo systemctl enable codex-time-bot.
• Disable autostart after reboot: sudo systemctl disable codex-time-bot.
• Disabling autostart does not stop the currently running service; use sudo systemctl stop codex-time-bot for that.

Logs:

sudo journalctl -u codex-time-bot -f