Termux bot Manager

Termux上でPython製Discord botを検出・起動・監視するためのツールです。 / A tool for discovering, starting, and monitoring Python-based Discord bots on Termux.

日本語 | English

---

日本語

概要

Termux bot ManagerはTermux上でPython製Discord botをまとめて管理するためのツールです。
指定ディレクトリを再帰的に探索し、特定のタグを含む .py ファイルを検出して起動します。
また、定期的な監視、再スキャン、キャッシュ管理、Discord Webhook通知を行います。

Tip

複数の Discord bot を同じ環境でホストしている方に特におすすめです。

主な機能

• タグベースの自動検出: 指定ディレクトリ内を再帰的に検索し、特定のタグが記述されたPythonスクリプトを自動でbotとして認識します。
• プロセス監視と自動起動: 検出したbotを起動し、定期的な監視サイクルによってプロセスの状態をチェックします。
• 定期再スキャンとキャッシュ自動整理: 新しく追加されたbotの自動検出に加え、削除・移動されたファイルのキャッシュ削除を自動で行います。
• Discord Webhook 通知: botの起動、異常終了、新規検出、キャッシュ削除などの各種イベントを Discord へリアルタイムに通知します。
• Bot ごとの独立したログ管理: 各botのディレクトリ内に標準出力（bot_stdout.log）と標準エラー（bot_stderr.log）を分離して保存します。

動作要件

• Node.js
• Python 3
• Termux
• Discord Webhook URL（通知を使う場合）

インストール

Termux上でインストールするには、Gitの導入とnpmの設定が必要です。

事前準備

pkg install git
npm config set allow-git all

方法1: npmから直接インストール（推奨）

npm install -g DovahkiinYuzuko/termux-bot-manager

方法2: git cloneを使う方法

環境によって方法1でエラーになる場合は、以下の手順を試してください。

git clone [https://github.com/DovahkiinYuzuko/termux-bot-manager.git](https://github.com/DovahkiinYuzuko/termux-bot-manager.git)
cd termux-bot-manager
npm install -g .

インストール完了後、pybot コマンドが利用可能になります。

設定ファイル

初回起動時に config.json が存在しない場合は、テンプレートが自動生成されます。
生成後に内容を編集してから再度起動してください。

config.json の例:

{
  "searchDirectory": "",
  "targetTags": ["@discordbot", "@auto"],
  "checkIntervalMinutes": 5,
  "rescanIntervalMinutes": 60
}

各項目

• searchDirectory: botを探索する対象ディレクトリです。
• targetTags: Pythonファイル内に含まれていればbotとみなすタグです。
• checkIntervalMinutes: 監視サイクルの実行間隔です。
• rescanIntervalMinutes: 新規 bot 検出のための再スキャン間隔です。未指定の場合は checkIntervalMinutes の値が使われます。

環境変数

.env.sample をコピーして .env を作成し、値を設定してください。

cp .env.sample .env

以下の値を設定できます。

DISCORD_WEBHOOK_URL=

• DISCORD_WEBHOOK_URL: Discord 通知の送信先 Webhook URL です。未設定の場合、通知は送信されません。

使い方

設定ファイルと環境変数を準備したあと、以下のコマンドで起動します。

pybot

開発時など、直接実行する場合は以下でも起動できます。

node index.js

事前準備と検出ルール

このツールは、指定ディレクトリ以下の .py ファイルを探索し、
ファイル内容に targetTags のいずれかが含まれている場合、そのファイルをbotとして扱います。

Important

ツールに bot として認識させるため、対象の Python ファイル内に 事前にタグを記述しておく 必要があります。 指定のワード（タグ）が含まれていれば起動対象になるため、記述する形式はコメントなど何でも構いません。

例:

# tag: @discordbot

ログと出力ファイル

• cache.json: 検出済みbotパスのキャッシュです。
• bot_stdout.log: 各botディレクトリに出力される標準出力ログです。
• bot_stderr.log: 各botディレクトリに出力される標準エラーログです。

Discord 通知

Discord Webhook を設定すると、以下のような通知を送信できます。

• botの起動
• botの異常終了
• bot起動時のエラー
• キャッシュからの削除
• 新規bot検出
• その他の情報通知

Termux環境でのPythonライブラリインストールについて

Note

Termux 環境では、Python ライブラリの導入方法によってインストール時間や成功率が大きく変わることがあります。
特に C コンパイル拡張を含むライブラリでは、この違いが重要です。

• pip install は利用できますが、C コンパイル拡張を含むライブラリでは Termux 上でソースビルドが走ることがあります。
• その場合、非力な CPU 環境では数分から数十分かかることがあります。
• たとえば Pillow や matplotlib では、この問題が起こることがあります。
• pkg で導入できるライブラリは、Termux 向けにビルド済みパッケージが提供されていることがあり、pip より大幅に速く導入できる場合があります。
• そのため、まず pkg search <ライブラリ名> で存在を確認し、見つかる場合は pkg install を優先することをおすすめします。
• pkg に存在しない場合は pip install を使用してください。
• ただし、pkg 版と pip 版ではバージョン差がある場合があるため、厳密なバージョン指定が必要なプロジェクトでは注意が必要です。

注意事項

Warning

• このツールは Python ファイル名やプロセス状態をもとに bot を管理します。
• 対象は Python 製 Discord bot を想定しています。
• 実行環境や運用方法によっては、意図しない判定が起こる可能性があります。
• Termux 上での利用を前提にしています。
• Python bot 側の依存関係や実行要件は、このツールとは別に準備してください。

LICENSE

このプロジェクトのライセンスは MIT License です。詳しくは LICENSE.MIT をお読みください。

---

English

Overview

Termux bot Manager is a tool for managing Python-based Discord bots on Termux.
It recursively scans a target directory, detects .py files containing specific tags, and starts them.
It also performs periodic monitoring, rescanning, cache management, and Discord Webhook notifications.

Tip

Highly recommended for those hosting multiple Discord bots in the same environment!

Features

• Tag-based Auto Detection: Recursively searches target directories and automatically identifies Python scripts containing specified tags as bots.
• Process Monitoring & Auto-Start: Launches detected bots and continuously monitors process status via periodic check cycles.
• Periodic Rescan & Cache Cleanup: Automatically scans for newly added bots and prunes missing or deleted files from the cache.
• Discord Webhook Notifications: Sends real-time alerts to Discord for events such as startups, crashes, new bot detections, and cache removals.
• Isolated Per-Bot Logging: Saves standard output (bot_stdout.log) and standard error (bot_stderr.log) logs independently inside each bot's directory.

Requirements

• Node.js
• Python 3
• Termux
• Discord Webhook URL (if notifications are used)

Installation

To install this package on Termux, Git and a specific npm configuration are required beforehand.

Prerequisites

pkg install git
npm config set allow-git all

Method 1: Direct installation via npm (Recommended)

npm install -g DovahkiinYuzuko/termux-bot-manager

Method 2: Installation via git clone

If the above method fails depending on your environment, try the following steps:

git clone [https://github.com/DovahkiinYuzuko/termux-bot-manager.git](https://github.com/DovahkiinYuzuko/termux-bot-manager.git)
cd termux-bot-manager
npm install -g .

After installation, the pybot command will be available.

Configuration

If config.json does not exist on first launch, a template is created automatically.
Please edit it before starting the application again.

Example config.json:

{
  "searchDirectory": "",
  "targetTags": ["@discordbot", "@auto"],
  "checkIntervalMinutes": 5,
  "rescanIntervalMinutes": 60
}

Fields

• searchDirectory: The target directory to scan for bots.
• targetTags: Tags used to identify Python files as bots.
• checkIntervalMinutes: Interval for the monitoring cycle.
• rescanIntervalMinutes: Interval for rescanning and detecting new bots. If omitted, the value of checkIntervalMinutes is used.

Environment Variables

Copy .env.sample to .env and set the values.

cp .env.sample .env

You can set the following value in .env:

DISCORD_WEBHOOK_URL=

• DISCORD_WEBHOOK_URL: The Discord Webhook URL used for notifications. If it is not set, notifications are not sent.

Usage

After preparing the configuration file and environment variables, start the application with:

pybot

For development or direct execution, you can also run:

node index.js

Preparation and Detection Rules

This tool scans .py files under the target directory.
If a file contains any of the values listed in targetTags, it is treated as a bot.

Important

To allow the tool to recognize your bot, you must add a tag to the target Python file beforehand. The format can be anything, such as a simple comment, as long as it contains the specified word.

Example:

# tag: @discordbot

Logs and Output Files

• cache.json: Cache file for detected bot paths.
• bot_stdout.log: Standard output log written in each bot directory.
• bot_stderr.log: Standard error log written in each bot directory.

Discord Notifications

When a Discord Webhook is configured, the tool can send notifications for:

• bot startup
• unexpected bot exit
• bot startup errors
• cache removal
• new bot detection
• other informational events

About Installing Python Libraries on Termux

Note

On Termux, the installation method for Python libraries can significantly affect both installation time and reliability.
This is especially important for libraries that include C extension builds.

• pip install works, but libraries with C extensions may trigger source builds on Termux.
• On low-power CPUs, this can take several minutes or even much longer.
• Libraries such as Pillow and matplotlib can fall into this category.
• Libraries available through pkg may be distributed as prebuilt packages for Termux, which can make installation much faster than pip.
• For this reason, it is recommended to first check with pkg search <library-name>, and use pkg install when available.
• If the package is not available through pkg, use pip install.
• However, package versions may differ between pkg and pip, so projects requiring strict version control should verify compatibility carefully.

Notes

Warning

• This tool manages bots based on Python file names and process state.
• It is intended for Python-based Discord bots.
• Depending on the runtime environment and operational setup, unintended matches or detections may occur.
• It is intended for use on Termux.
• Dependencies and runtime requirements for each Python bot must be prepared separately.

LICENSE

This project is licensed under the MIT License. Please read LICENSE.MIT for details.