@pasky/muaddib

🐁 Muaddib - a secure, multi-user AI assistant

Muaddib is an AI agent that's been built from the ground up not as a private single-user assistant (such as OpenClaw), 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).

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.6 recommended), OpenAI, DeepSeek, any OpenRouter model (including Gemini models)
• Agentic Capability: Ability to visit websites, view images, perform deep research, fully sandboxed and isolated code execution and long-term state maintenance, publish artifacts; each channel/DM gets a persistent sandboxed workspace with long-term state (code, data, installed packages)
• Continuous Learning: AI agent maintains short-term memory (smart context engineering), mid-term memory (a scratchpad), and long-term memory both episodic (a continuous chronicle of events and experiences) and procedural (automatically maintained skills)
• Command System: Automatic model routing (to balance cost, speed and intelligence) plus multiple, extensible "command modes" based on specific prefixes
• Proactive Interjecting: Lurk-by-default with a opt-in automatic participation in relevant conversations
• Semi-Secure Enclaves: Hardening for environments with secrets (Gondolin-based tokens injection without sandbox exposure) and opt-in manual network access approval mechanism

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 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
├── arcs/               # Per-arc data (one subdir per channel/DM)
│   └── <arc>/
│       ├── chat_history/   # JSONL chat logs (one file per day)
│       ├── chronicle/      # Markdown chronicle entries
│       ├── workspace/      # Gondolin VM persistent workspace (mounted at /workspace)
│       └── checkpoint.qcow2  # Gondolin VM disk checkpoint
├── 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 (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

First, Muaddib runs agent code in isolated QEMU micro-VMs (Gondolin) - to set it up:

sudo apt install qemu-system qemu-utils lz4
./scripts/build-gondolin-image.sh

Then, combine one or more of the following:

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

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

IRC

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
• !balance / !setkey - Manage per-user spending and custom openrouter keys
• !approve / !deny - Approve/deny a blocked untrusted network request

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

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.