Skip to main content
ollim-bot is single-user by design. There is no multi-tenancy, no shared hosting, no user accounts. If you want your own instance, you fork the repo, configure it for yourself, and run it. This guide covers the full process.

​
Prerequisites

  • uv — curl -LsSf https://astral.sh/uv/install.sh | sh (automatically installs the required Python version)
  • A Claude subscription (Pro or Max) — the bot authenticates via the bundled Agent SDK CLI at startup. If you plan to use a local or alternative model provider, you don’t need a Claude subscription.
  • A Discord account (the bot runs entirely in DMs — no server required)
  • Git installed (the data directory is a git repo)

​
Installation

Follow the quickstart guide to get the bot running, then set up Google integration for Tasks, Calendar, and Gmail. The steps below cover self-hosting-specific setup.
1

Fork the repository

Fork the repo on GitHub, then clone your fork:
git clone https://github.com/<your-username>/ollim-bot.git
cd ollim-bot
uv sync
uv tool install --editable .
uv sync installs dependencies. uv tool install makes ollim-bot and claude-history available as global commands. claude-history is a CLI tool used by subagents to review Claude Code session transcripts.Working from a fork lets you customize the system prompt, subagent prompts, and integrations while still pulling upstream changes.
2

Create a Discord bot

Create a Discord application at the Discord Developer Portal. You need the bot token and the Message Content privileged intent.See the quickstart for the full walkthrough.
3

Set up Google OAuth (optional)

Google Tasks, Calendar, and Gmail integration requires OAuth credentials from Google Cloud Console. Download the credentials JSON and save it to ~/.ollim-bot/state/credentials.json, then run /google-auth in Discord to connect your account.See Google integration setup for the full walkthrough.
4

Run the bot

ollim-bot
On startup, ollim-bot validates environment variables and checks Claude authentication via is_authenticated(). If not logged in, the bot extracts an OAuth URL from the bundled CLI and DMs it to you using the Discord REST API — this happens before the bot fully connects, so you receive the link even on a headless server with no browser. Click the link to sign in with your Anthropic account. The bot blocks until authentication completes, then continues startup.Once authenticated, the bot checks for duplicate instances, connects to Discord, starts the scheduler, and sends you a startup DM.
If you’re using an alternative provider (Ollama, vLLM, etc.), set ANTHROPIC_AUTH_TOKEN in your .env — the Agent SDK uses this token instead of Claude OAuth, so no Anthropic account is needed. See Model providers for provider-specific .env configuration.
ollim-bot enforces single-instance via a PID file. On startup, it checks whether the recorded PID is still alive, so stale PID files from crashes are handled automatically.

​
What to customize

ollim-bot is designed to be personalized. The main customization points:

​
Names and identity

Set OLLIM_USER_NAME and OLLIM_BOT_NAME in .env. These are woven into the system prompt and all bot messages. The bot addresses you by OLLIM_USER_NAME and refers to itself by OLLIM_BOT_NAME.

​
System prompt

The system prompt is built in src/ollim_bot/prompts.py. It includes tool instructions, scheduling context, and behavioral guidelines. Edit this file to change the bot’s personality, communication style, or default behaviors.

​
Subagent prompts

Subagent specs live in src/ollim_bot/subagents/ as markdown files with YAML frontmatter. ollim-bot ships with five subagents:
SubagentPurpose
ollim-bot-guideDocs-first setup and usage help
gmail-readerRead-only email triage
history-reviewerReviews session history for context
responsiveness-reviewerEvaluates the bot’s own proactive behavior
user-proxyAnswers “what would the user prefer?” during background forks
Place override files in ~/.ollim-bot/.claude/agents/ to modify these prompts — install_agents() skips files that already exist, so your customizations persist across bot updates. Create additional spec files in src/ollim_bot/subagents/ to add new bundled subagents.

​
Model providers

By default, ollim-bot uses your Claude subscription via Claude Code OAuth. You can also use alternative model subscriptions (from $3/month), pay-per-token providers, or self-hosted models. See Model providers for all options.

​
Integrations

To add a new Google service: add the OAuth scope to google/auth.py, create a new module in google/, and add tool instructions to the system prompt. See Adding integrations for the full pattern.

​
Routines and reminders

Routines and reminders are markdown files in ~/.ollim-bot/routines/ and ~/.ollim-bot/reminders/. The agent creates and manages these files directly, but you can also create them manually or via the CLI: 
ollim-bot routine add --cron "0 9 * * 1-5" -m "Morning briefing"
ollim-bot reminder add --delay 30 -m "Take a break"

​
Data directory

All persistent data lives in ~/.ollim-bot/, managed as a git repository. See Data directory for the full layout.
Back up ~/.ollim-bot/ to preserve your routines, reminders, session history, and Google credentials. Since it is a git repo, you can push it to a private remote for backup.

​
Docker deployment

The repo ships a Dockerfile, docker-compose.yml, and docker-entrypoint.sh for containerized deployment. The compose file bundles ollim-bot with a local Ollama server, so a single docker compose up gives you a self-contained stack with no Anthropic account required for inference.
1

Configure .env

Create a .env file in the repo root. At minimum you need DISCORD_TOKEN, OLLIM_USER_NAME, and OLLIM_BOT_NAME. To use the bundled Ollama service, point the bot at the ollama service hostname and set any non-empty ANTHROPIC_AUTH_TOKEN:
.env
DISCORD_TOKEN=your-discord-bot-token
OLLIM_USER_NAME=YourName
OLLIM_BOT_NAME=Ollim
ANTHROPIC_BASE_URL=http://ollama:11434
ANTHROPIC_AUTH_TOKEN=ollama
ANTHROPIC_MODEL=qwen3.5:2b
ANTHROPIC_SMALL_FAST_MODEL=qwen3.5:2b
Setting ANTHROPIC_AUTH_TOKEN tells ollim-bot to skip the Claude OAuth check at startup — necessary inside containers where the bundled CLI can’t prompt for login. See Model providers for other backend options.
2

Start the stack

docker compose up -d
The entrypoint (docker-entrypoint.sh) checks whether ANTHROPIC_MODEL is already present on the Ollama server and pulls it automatically if not — the first start may take several minutes while the model downloads. Compose waits for Ollama’s healthcheck before starting the bot container.
3

Tail logs and verify

docker compose logs -f ollim-bot
Once the bot connects to Discord, you receive the startup DM. Use docker compose down to stop and docker compose up -d --build to rebuild after changing source or prompts.

​
What the compose stack does

ServiceImagePurpose
ollamaollama/ollamaLocal Ollama server bound to 127.0.0.1:11434 on the host
ollim-botBuilt from local DockerfileThe bot, depending on ollama being healthy
VolumeMounted atPurpose
ollama_data/root/.ollama (in ollama)Pulled Ollama models persist across restarts
bot_data/home/bot/.ollim-bot (in ollim-bot)Data directory — routines, reminders, sessions, profile files
cli_data/home/bot/.claude (in ollim-bot)Claude CLI configuration
The bot container runs as an unprivileged bot user. The Ollama port is bound to 127.0.0.1 on the host so it isn’t reachable from other machines on your network.
To use a cloud provider (Claude subscription, Z.AI, DeepSeek, etc.) instead of bundled Ollama, set the provider’s ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in .env and remove the ollama service and its depends_on entry from docker-compose.yml. See Model providers for provider configurations.
The bot container can’t complete Claude OAuth on your behalf — there’s no browser inside. Either set ANTHROPIC_AUTH_TOKEN (any provider, including Ollama) to skip OAuth entirely, or run the bot natively once to complete login before switching to Docker.

​
Running as a service

For persistent operation without Docker, run ollim-bot as a systemd user service:
~/.config/systemd/user/ollim-bot.service
[Unit]
Description=ollim-bot Discord assistant
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=<path-to-ollim-bot>
ExecStart=<path-to>/.local/bin/ollim-bot
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
Reload the service configuration and start the bot: 
systemctl --user daemon-reload
systemctl --user enable --now ollim-bot
The bot sends you a DM before shutting down on crash, SIGINT, or SIGTERM — you’ll see a message like shutting down: received SIGTERM. Combined with Restart=on-failure, this means you get notified and the bot comes back automatically.
If Claude Code is not authenticated when the service starts, the bot DMs you an OAuth link and blocks until you complete sign-in. The systemd service may time out waiting — run ollim-bot auth login once manually before enabling the service. If you’re using an alternative provider with ANTHROPIC_AUTH_TOKEN, this step is not needed.

​
Session persistence

ollim-bot persists its Claude session across restarts — no context is lost. If you want a fresh start, use /clear in Discord. See Session management for details on compaction, lifecycle events, and session recovery.

​
License

ollim-bot is licensed under GPL-3.0. If you fork the repo and distribute your modified version, your fork must also be released under GPL-3.0 and include the full source — that’s what copyleft means. Running your own private fork for personal use has no such requirement. The license also carries a Section 7 supplementary notice restricting use of the repo’s contents for training or evaluating machine learning models without written permission from the copyright holder. This does not affect normal human use, modification, or redistribution under GPL-3.0.

​
Next steps

Choose a model provider

Use a local model, alternative subscription, or pay-per-token provider.

Quickstart

Install ollim-bot and create a Discord bot.

Configuration reference

All environment variables and configuration options.

System prompt

How the system prompt is structured and how to customize it.