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.

​
Running as a service

For persistent operation, 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.

​
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.