Alatar Bot

Alatar Bot is a Discord bot for server management, activity monitoring, and automated voice channel organization. It is built with discord.py 2.x and targets Python 3.10+.

Features

• Slash commands for admin-only moderation and utility actions
• User activity tracking for presence, voice state, and channel events
• Automated voice channel organization based on selected games or activities
• Welcome messages and automatic "Plebs" role assignment for new members
• Ignore list management for activity logging
• DM notifications to the configured admin, with queueing when notifications are disabled
• Rotating log files for bot output and per-user activity history
• Slash commands for invites, server info, and random insults

Requirements

• Python 3.10 or newer
• A Discord bot token
• The Discord user ID of the admin account that should receive notifications

Installation

1. Clone or download this repository.

2. Create the repository-local virtual environment and install dependencies:

   python3 -m venv .venv
   .venv/bin/python -m pip install --upgrade pip
   .venv/bin/python -m pip install --requirement requirements.txt

   You can also install the project as a package inside the virtual environment:

   .venv/bin/python -m pip install .

3. Run the bot:

   .venv/bin/python Alatar_Bot.py

Server deployment

For a Linux or GCP VM, keep the virtual environment inside the repository and use the deployment scripts:

bash scripts/setup.sh
./start.sh
./scripts/status.sh
./stop.sh
./update.sh

setup.sh creates .venv, installs requirements.txt, and checks that the bot compiles. start.sh stops any PID-managed bot instance that is already running before starting a fresh process. update.sh discards tracked and non-ignored untracked local changes, fetches origin, and resets the checkout to the configured branch (default: master). It restores lifecycle-script permissions, refreshes dependencies when the revision changes, and restarts the bot if it was running. Runtime files such as settings.json, logs, the PID file, and .venv remain local and are not changed by Git.

For automatic restarts on VM reboot, run ./scripts/install-systemd.sh after setup. The command installs a systemd unit using the current repository path; manage it with sudo systemctl restart alatar-bot and inspect output with sudo journalctl -u alatar-bot -f. Once installed, update.sh detects the active unit and stops/starts it through systemd instead of using the PID-based lifecycle.

Inviting the Bot

To invite Alatar Bot to your Discord server, you will need to generate an invite link from the Discord Developer Portal.

1. Get your Bot's Client ID:

   • Go to the Discord Developer Portal.
   • Select your bot application.
   • Navigate to "OAuth2" -> "General". Your "Client ID" will be listed there.

2. Generate the Invite Link:

   • Navigate to "OAuth2" -> "URL Generator".
   • Under "SCOPES", select bot and applications.commands.
   • Under "BOT PERMISSIONS", select the following recommended permissions:
     • General Permissions:
       • View Channels
       • Send Messages
       • Embed Links
       • Read Message History
       • Use Application Commands
     • Membership Permissions:
       • Manage Roles
       • Kick Members
       • Ban Members
     • Voice Channel Permissions:
       • Connect
       • Speak
       • Move Members
       • Manage Channels
   • Copy the generated URL from the "GENERATED URL" box.

3. Invite to your Server:

   • Paste the copied URL into your browser.
   • Select the server you wish to invite the bot to and authorize it.

Configuration

Runtime configuration lives in settings.json.

The file is created automatically on first run if it does not already exist.

Settings

{
    "discord_token": "your-bot-token-here",
    "admin_discord_id": "123456789012345678",
    "log_rotation_when": "midnight",
    "log_rotation_interval": 1,
    "log_backup_count": 30,
    "ignored_members": []
}

Field Reference

Field	Description	Required
discord_token	Discord bot token from the Developer Portal	Yes
admin_discord_id	Discord user ID that receives admin notifications	Yes
log_rotation_when	Time unit for bot log rotation, such as midnight, D, or H	No
log_rotation_interval	Number of time units between bot log rotations	No
log_backup_count	Number of rotated bot log files to keep	No
ignored_members	Member display names excluded from activity logging	No

Environment Variables

These optional environment variables override values in settings.json:

• DISCORD_TOKEN
• DISCORD_BOT_TOKEN
• ADMIN_DISCORD_ID

Usage

On startup, the bot loads settings, syncs slash commands, and connects to Discord. If the bot is missing a token or admin ID, it prompts for them when run interactively. When notifications_enabled is turned off through /off, messages to the admin are queued until /on re-enables delivery. Admin notifications use native Discord Embed timestamps, so they automatically render in the timezone of your Discord client. Per-member activity log files continue to use UTC so events remain consistent across machines and daylight-saving changes. Presence status notifications include a device label only when that device is active for the corresponding status, such as now OFFLINE, was ONLINE (WEB).

Commands

Slash Commands

Command	Description
/on	Turn admin notifications on and flush queued notifications
/off [seconds_delay]	Turn admin notifications off, optionally re-enabling after a delay
/ignore <target_member_name>	Add a member display name to the ignore list
/unignore <target_member_name>	Remove a member display name from the ignore list
/unignoreall	Clear the ignore list
/invite <invite_target>	Invite a user to your current voice channel
/printignored	Show the current ignore list
/printnotignored	Show members not on the ignore list
/printseeking	Show members currently seeking playmates
/insult <insult_target>	Send a random insult to a user
/serverinfo	Display information about the current server

Prefix Commands

The bot still uses ! as its command prefix for legacy command handling and error routing, but the primary user-facing commands are slash commands.

Logging

• discord.log stores the current bot-level log and rotates automatically at midnight UTC by default.
• Rotated files use dated names such as discord.log.2026-08-29 and retain the latest 30 files by default.
• Set log_rotation_when and log_rotation_interval in settings.json to change the schedule.
• logs/<display-name>.txt stores per-member activity history with UTC timestamps.
• Timestamped admin DMs use native Discord Embed timestamps and inherit the Discord client's timezone preferences.

Project Structure

Alatar_Bot.py      Main bot source
pyproject.toml     Packaging and tooling configuration
requirements.txt   Dependency list
start.sh            Start the bot
stop.sh             Stop the bot
update.sh           Update the bot and restart it when needed
scripts/            Setup, status, shared, and systemd installation scripts
deploy/             systemd service template
settings.json      Runtime configuration
README.md          Project overview and setup
CHANGELOG.md       Version history
CONTRIBUTING.md    Contribution guide
AGENTS.md          Agent-specific coding instructions
discord.log        Time-rotating bot log
logs/              Per-user activity logs

Dependencies

• discord.py>=2.3.0
• requests>=2.31.0

Troubleshooting

• If slash commands do not appear, make sure the bot has been invited with the correct scopes and has permission to read the guild.
• If the bot cannot DM the admin, confirm the admin account accepts direct messages from the server.
• If voice organization is not working, verify the bot has Manage Channels and Move Members permissions.
• If the bot asks for configuration repeatedly, confirm settings.json is writable and contains valid JSON.
• If /off <seconds_delay> is used with a delay, the bot will schedule re-enabling notifications in the background.

License

This project is provided as-is for personal Discord server management use.

Acknowledgments

• Evil Insult API for the insult command
• The Discord.py community for documentation and examples