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)
  • Claude Code — curl -fsSL https://claude.ai/install.sh | bash then run claude to authenticate. A Claude subscription (Pro or Max) is recommended for access to the latest models.
  • 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 to get the bot running, then Optional integrations for Google OAuth, webhooks, etc. 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 tool install --editable .
uv tool install claude-history@git+https://github.com/Ollim-AI/claude-history.git
The first command installs ollim-bot as a global command. claude-history is a global 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 Discord bot setup 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.See Google OAuth setup for the full walkthrough.
4

Run the bot

ollim-bot
On startup, ollim-bot validates environment variables, checks for duplicate instances, connects to Discord, starts the scheduler, and sends you a startup DM.
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 prompts live in src/ollim_bot/subagent_prompts.py. ollim-bot ships with three subagents:
SubagentPurpose
gmail-readerRead-only email triage
history-reviewerReviews session history for context
responsiveness-reviewerEvaluates the bot’s own proactive behavior
You can modify these prompts or add new subagents by defining additional AgentDefinition entries in agent.py.

​
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

systemctl --user daemon-reload
systemctl --user enable --now ollim-bot
Claude Code must be authenticated before starting the service. Run ollim-bot interactively first to complete any auth flows, then enable the systemd service.

​
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

Discord bot setup

Create a Discord application, bot token, and enable required intents.

Google OAuth setup

Set up Google Tasks, Calendar, and Gmail integration.

Configuration reference

All environment variables and configuration options.

System prompt

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