AI Bot Players#

Overdue includes AI bot players that populate the leaderboard with simulated activity. Bots create a dynamic competitive environment -- their XP shifts each time the server starts, keeping the leaderboard interesting.

Overview#

Bots are managed via CLI commands. Each bot has a difficulty profile that determines how active it is:

Bots appear on the leaderboard with a robot indicator so real players can distinguish them.

Managing bots with Docker Compose#

The recommended way to run CLI commands is through Docker Compose. This ensures the commands run against the same database the server uses.

Add bots#

# Add a single casual bot
docker compose exec overdue overdue bots add casual

# Add 3 diligent bots
docker compose exec overdue overdue bots add diligent --count 3

# Add an obsessive bot with a custom name
docker compose exec overdue overdue bots add obsessive --name overlord99

List bots#

docker compose exec overdue overdue bots list

Displays a table with each bot's ID, username, difficulty, XP, rank, and avatar.

Simulate activity#

Bot activity is automatically simulated each time the server starts. You can also trigger it manually:

# Simulate all bots
docker compose exec overdue overdue bots simulate

# Simulate a specific bot
docker compose exec overdue overdue bots simulate --name bookworm42

Each simulation round awards XP, may add reviews, and updates streaks based on the bot's difficulty profile.

Remove bots#

# Remove a specific bot
docker compose exec overdue overdue bots remove bookworm42

# Remove all bots
docker compose exec overdue overdue bots remove --all

Removing a bot deletes all its related data: volumes (including reviews left by other librarians on those volumes and the volumes' bookmark rows), the bot's own reviews, XP ledger, badges, streaks, and bulletins (webhook subscriptions). Shelves are never touched -- bots don't own shelves.

Running locally (without Docker)#

If you're running Overdue directly on your machine:

# Use the overdue CLI entry point
overdue bots add casual --count 2
overdue bots list
overdue bots simulate
overdue bots remove --all

Seed bots#

When the database is first created (auto-seed on startup), two bots are included automatically:

• bookworm42 -- a casual bot
• scholar_jane -- a diligent bot

These provide an active leaderboard out of the box. You can remove them with bots remove --all and add your own mix.

How simulation works#

On each server startup, simulate_bot_activity() runs for all existing bots:

1. Each bot gains XP based on its difficulty tier
2. Bots may create new reviews on their volumes
3. Streaks are extended or reset (weighted by difficulty -- obsessive bots rarely lose streaks)
4. Ranks are recalculated if XP crosses a threshold

This means every server restart shuffles the leaderboard slightly, creating a living competitive environment.

Bot avatars#

Each bot is assigned a random heroic librarian avatar from the 8 available designs. These appear on the leaderboard and profile pages alongside the robot indicator.