@pasky/muaddib

🐁 Muaddib - a secure, multi-user AI assistant

Muaddib is an AI assistant that's been built from the ground up not as a private single-user assistant (such as the amazing Clawdbot / Moltbot), but as a resilient entity operating in an inherently untrusted public environment (public IRC / Discord / Slack servers).

What does it take to talk to many strangers?

• It operates sandboxed, and with complete channel isolation.
• It has been optimized for high cost and token efficiency (using a variety of context engineering etc. techniques).
• It operates in "lurk" mode by default (rather than replying to everything, Muaddib replies when highlighted, but can also interject proactively when it seems useful).

Other work-in-progress features are also going to be tailored to this scenario (e.g. per-user token usage tracking and limiting / billing, per-channel code secrets and persistent workspaces, ...).

Of course, this means a tradeoff. Muaddib is not designed to sift through your email and manage your personal calendar! It is tailored for public and team environments, where it's useful to have an AI agent as a "virtual teammate" - both as an AI colleague in chat for public many-to-many collaboration, and allowing personal or per-channel contexts.

Quick Demo

Muaddib maintains a refreshing, very un-assistanty tone of voice that optimizes for short, curt responses (sometimes sarcastic, always informative) with great information density. And you may quickly find that Muaddib (in this case equipped with Opus 4.5) can do things that official Claude app does much worse (let alone other apps like ChatGPT or Gemini!).

➜ Generated image

(By the way, the token usage has been optimized since!)

Of course, as with any AI agent, the real magic is in chatting back and forth. (Multiple conversations with several people involved can go on simultaneously on a channel and Muaddib will keep track!)

(➜ Generated image, in case you are curious)

(Note that this particular task is on the edge of raw Opus 4.5 capability and all other harnesses and apps I tried failed it completely.)

Discord is of course supported:

So is Slack - including threads:

Features

• AI Integrations: Anthropic Claude (Opus 4.5 recommended), OpenAI, DeepSeek, any OpenRouter model (including Gemini models)
• Agentic Capability: Ability to visit websites, view images, perform deep research, execute Python/Bash code via Sprites, publish artifacts
• Restartable and Persistent Memory: All state is persisted; AI agent maintains a continuous chronicle of events and experiences to refer to
• Command System: Automatic model routing (to balance cost, speed and intelligence) plus extensible command-based interaction with prefixes for various modes
• Proactive Interjecting: Channel-based whitelist system for automatic participation in relevant conversations
• [BETA] Long-running Projects: A quest mode (opt-in) that enables Muaddib to work on longer-horizon, many-step tasks in public, using the channel for long-term context and external steering

Muaddib has been battle-tested since July 2025 in a (slightly) hostile IRC environment, lurking at a variety of libera.chat channels. However, bugs are possible (no warranty etc.) and LLM usage carries some inherent risks (e.g. a Sprites code execution sandbox with your API keys preloaded plus an access to the internet can be fooled by a highly crafted malicious website that the agent visits to upload these API keys somewhere).

Getting Started

Configuration

All muaddib data lives in $MUADDIB_HOME (defaults to ~/.muaddib/):

~/.muaddib/
├── config.json         # Configuration (no secrets)
├── auth.json           # API keys and secrets
├── chat_history.db     # Chat history database
├── chronicle.db        # Chronicle database
├── artifacts/          # Published artifacts
└── logs/               # Per-message log files

• Copy config.json.example to ~/.muaddib/config.json and configure:

  • Provider endpoints and model settings
  • Paths for tools and artifacts (relative paths are resolved against $MUADDIB_HOME)
  • Custom prompts for various modes
  • Room integration settings (channels, modes, proactive behavior)

• Copy auth.json.example to ~/.muaddib/auth.json and set your API keys:

  • Provider keys (anthropic, openai, openrouter, deepseek, etc.)
  • Tool keys (sprites, jina, brave)
  • Room tokens (discord, slack-app, slack-{workspaceId})

Tip: Set MUADDIB_HOME=. to use the current directory (useful for development).

Migrating from older versions: If you previously had API keys in config.json, run npx tsx scripts/migrate-auth.ts to extract them into auth.json, then manually remove the secret fields from config.json.

Installation

Recommended for Discord:

• Follow Discord setup instructions to create a bot account and obtain a token. Set it in ~/.muaddib/auth.json as the discord key.
• Install dependencies: npm ci
• Build runtime: npm run build
• Run the service: npm run start

Recommended for Slack:

• Follow Slack setup instructions to create a Slack app, enable Socket Mode, and obtain tokens.
• Set the Slack config block in ~/.muaddib/config.json and tokens in ~/.muaddib/auth.json.
• Install dependencies: npm ci
• Build runtime: npm run build
• Run the service: npm run start

Recommended for an IRC bot: See Docker instructions for running a Muaddib service + irssi in tandem in a Docker compose setup.

Manual for IRC ("bring your own irssi"):

• Ensure irssi-varlink is loaded in your irssi, and your varlink path is set up properly in ~/.muaddib/config.json IRC section.
• Install dependencies: npm ci
• Build runtime: npm run build
• Run the service: npm run start

Commands

• mynick: message - Automatic mode
• mynick: !h - Show help and info about other modes

Architecture

Muaddib is built on the pi-coding-agent SDK (@mariozechner/pi-agent-core and @mariozechner/pi-ai) for its agent runtime, but defines its own complete tool set (code execution, web search, artifacts, etc.) — pi's built-in tools are not used.

Development

# Install dependencies
npm ci

# Typecheck + tests
npm run typecheck
npm test

# Build
npm run build

CLI Testing Mode (TypeScript)

You can test command parsing and response flow from the command line:

npm run cli:message -- --message "!h"
npm run cli:message -- --message "tell me a joke"
npm run cli:message -- --message "!d tell me a joke"
npm run cli:message -- --message "!a summarize https://python.org"
# Or with explicit config:
# npm run cli:message -- --message "!a summarize https://python.org" --config /path/to/config.json

This simulates full room command handling without running the full chat service.