Mudabbir

An AI agent that runs on your machine, not someone else's.

Self-hosted, multi-agent AI platform. Web dashboard + Discord, Slack, WhatsApp, Telegram, and more.
No subscription. No cloud lock-in. Just you and your Paw.

🚧 Beta: This project is under active development. Expect breaking changes between versions.

Quick Start

curl -fsSL https://mudabbir.fly.dev/install.sh | sh

If your Linux shell shows parsing errors (for example : not found or set: Illegal option -), use:

curl -fsSL https://mudabbir.fly.dev/install.sh | tr -d '\r' | sh

Or install directly:

pip install Mudabbir && mudabbir

That's it. One command. 30 seconds. Your own AI agent.

I'm your self-hosted, cross-platform personal AI agent. The web dashboard opens automatically. Talk to me right in your browser, or connect me to Discord, Slack, WhatsApp, or Telegram and control me from anywhere. I run on your machine, respect your privacy, and I'm always here.

No subscription. No cloud lock-in. Just you and me.

More install options

# Isolated install
pipx install mudabbir && mudabbir

# Run without installing
uvx mudabbir

# From source
git clone https://github.com/Ahmed5754/mudabbir.git
cd mudabbir
uv run mudabbir

Mudabbir will open the web dashboard in your browser and be ready to go. No config files. No YAML. No dependency hell.

Talk to your agent from anywhere: Telegram · Discord · Slack · WhatsApp · Web Dashboard

Docker

Run Mudabbir in a container — great for servers, VPS, or always-on setups.

# Clone the repo
git clone https://github.com/Ahmed5754/mudabbir.git
cd mudabbir

# Copy and fill in your env vars
cp .env.example .env

# Start the dashboard
docker compose up -d

Dashboard is at http://localhost:8888. Log in with the access token:

docker exec mudabbir cat /home/mudabbir/.mudabbir/access_token

Optional services (Ollama, Qdrant)

# With Ollama for local LLM inference
docker compose --profile ollama up -d

# With Qdrant for mem0 vector memory
docker compose --profile qdrant up -d

# Both
docker compose --profile ollama --profile qdrant up -d

When using Ollama inside Docker, set MUDABBIR_OLLAMA_HOST=http://ollama:11434 in your .env so Mudabbir reaches the Ollama container by service name.

Data persists in a named Docker volume across restarts. See .env.example for all available configuration options.

What Can Mudabbir Do?

Feature	Description
Web Dashboard	Browser-based control panel, the default mode. No setup needed.
Multi-Channel	Discord, Slack, WhatsApp (Personal + Business), Signal, Matrix, Teams, Google Chat, Telegram
Claude Agent SDK	Default backend. Official Claude SDK with built-in tools (Bash, Read, Write).
Smart Model Router	Optional auto-selection of Haiku / Sonnet / Opus based on task complexity (off by default — Claude Code has its own routing)
Tool Policy	Allow/deny control over which tools the agent can use
Plan Mode	Require approval before the agent runs shell commands or edits files
Browser Control	Browse the web, fill forms, click buttons via accessibility tree
Gmail Integration	Search, read, and send emails via OAuth (no app passwords)
Calendar Integration	List events, create meetings, meeting prep briefings
Google Drive & Docs	List, download, upload, share files; read and create documents
Web Search & Research	Tavily/Brave search + multi-step research with source synthesis
Image Generation	Google Gemini image generation, saved locally
Voice / TTS / STT	Text-to-speech via OpenAI or ElevenLabs, speech-to-text via Whisper
Spotify	Search tracks, playback control, playlist management
Reddit	Search posts, read threads, browse trending topics
OCR	Extract text from images via GPT-4o vision or pytesseract
Memory & Compaction	Long-term facts + session history with smart compaction + Mem0 semantic search
MCP Support	Connect Model Context Protocol servers (stdio + HTTP)
Cron Scheduler	Recurring reminders with natural language time parsing
Security Suite	Injection scanner, audit CLI, Guardian AI, self-audit daemon
Local-First	Runs on YOUR machine. Your data never leaves your computer.
Cross-Platform	macOS, Windows, Linux
Skill System	Create reusable agent skills at runtime
Task Delegation	Delegate complex sub-tasks to Claude Code CLI

Examples

You:  "Every Sunday evening, remind me which recycling bins to put out"
Paw:  *creates a recurring schedule*
Paw:  "Done. I'll check the recycling calendar and message you every Sunday at 6pm."

You:  "Organize my Downloads folder. PDFs by date, images by type, delete duplicates"
Paw:  *scans filesystem, moves 47 files, removes 12 duplicates*
Paw:  "All clean. Here's what I did: [summary]"

Research & Browsing

You:  *drops a link*
Paw:  *opens browser, reads the page, researches related topics*
Paw:  "Here's a summary with 3 key takeaways. Want me to save this to memory?"

Coding & DevOps

You:  "Find that memory leak, the app crashes after 2 hours"
Paw:  *reads logs, profiles code, identifies the issue*
Paw:  "Found it. The WebSocket handler never closes connections. Here's the fix."

Multi-Agent Workflows (Mission Control)

You:  "I need a competitor analysis report for our product launch"
Paw:  *spins up Agent A: web researcher, Agent B: data analyst, Agent C: writer*
Paw:  "3 agents working on it. Agent A is scraping competitor sites,
       Agent B is analyzing pricing data, Agent C is waiting to write the report.
       I'll ping you when it's ready."

Web Dashboard

The browser-based dashboard is the default mode. Run mudabbir and it opens at http://localhost:8888.

What you get:

Real-time streaming chat via WebSocket
Session management: create, switch, search, and resume conversations
Activity panel showing tool calls, thinking, and system events
Settings panel for LLM, backend, and tool policy configuration
Channel management: configure, start, and stop adapters from the sidebar
MCP server management: add, configure, and monitor MCP servers
Plan Mode approval modal for reviewing tool calls before execution

Channel Management

All configured channel adapters auto-start on launch. Use the sidebar "Channels" button to:

Configure tokens and credentials per channel
Start/stop adapters dynamically
See running status at a glance

Headless mode is also available for running without the dashboard:

mudabbir --discord              # Discord only
mudabbir --slack                # Slack only
mudabbir --whatsapp             # WhatsApp only
mudabbir --discord --slack      # Multiple channels
mudabbir --telegram             # Legacy Telegram mode

See Channel Adapters documentation for full setup guides.

Browser

Uses your existing Chrome if you have it. No extra downloads. If you don't have Chrome, a small browser is downloaded automatically on first use.

Windows Skills Coverage (31-39 + AI)

Mudabbir now includes a large Windows desktop skillset covering your requested categories:

31. Background Apps Skills: background_tools (count_background, list_minimized_windows, list_visible_windows, ghost_apps, activity_time, network_usage_per_app, camera_usage_now, mic_usage_now, wake_lock_apps, process_paths)
32. Startup Skills: startup_tools (list, impact_breakdown, disable, enable, registry_startups, folder_startups, detect_new, watch_new_live, signature_check, full_audit)
33. Resource Monitoring: performance_tools (top_cpu, top_ram, top_disk, total_cpu_percent, total_ram_percent, cpu_clock, available_ram, top_gpu_processes, gpu_temp, pagefile_used, disk_io_rate)
34. App Killing & Cleaning: process_tools (kill_name, kill_pid, kill_unresponsive, kill_high_cpu, close_browsers, close_office, restart_explorer) + maintenance_tools (empty_ram)
35. Deep System Info: hardware_tools + info_tools + driver_tools + update_tools (cores_info, ram_speed_type, mobo_model, battery_minutes, battery_cycle_count, drivers_issues, windows_install_date, last_update_time)
36. Advanced UI Skills: window_control (set_focus, transparency, borderless_on/off, disable_close_on/off, minimize_to_tray, span_all_screens, move_resize)
37. Security Awareness: security_tools (logged_in_users, recent_files, recent_files_clear, current_connections_ips, firewall_status, admin_processes, failed_audit_logins, intrusion_summary, remote_sessions_list, close_remote_sessions)
38. Smart Utilities: text_tools, search_tools, screenshot_tools, automation_tools, ui_tools, service_tools (clipboard_to_file, search_open_windows_content, screenshot-to-path, timer, mouse lock/region, anti-idle F5, battery guard, screen-off mouse lock, refresh_rate, user_services, game_mode_on/off)
39. Dev Integration: dev_tools (open_editor, env_vars, runtime_versions, git_last_log, create_batch via text_tools) + interpret_powershell
AI Add-ons: vision_tools (screen description + OCR), threat_tools (behavior_scan, vt_lookup, file hash), file_tools semantic organization and smart content rename, content_tools (email/Word drafts + text-to-Excel)

Deterministic-First Windows Routing

Windows desktop/system requests are now matched against a deterministic intent map first.
If a request is mapped, Mudabbir executes the prebuilt DesktopTool action directly.
Open Interpreter generative execution is used only as fallback for unmapped requests.
Destructive commands (for example shutdown/restart/delete/registry/service-stop) use a one-step confirmation gate before execution.
Unsupported commands return explicit "not supported yet" responses instead of guessing.

Architecture

Agent Backends

Claude Agent SDK (Default, Recommended). Anthropic's official SDK with built-in tools (Bash, Read, Write, Edit, Glob, Grep, WebSearch). Supports PreToolUse hooks for dangerous command blocking.
Mudabbir Native. Custom orchestrator: Anthropic SDK for reasoning + Open Interpreter for code execution.
Open Interpreter. Standalone, supports Ollama, OpenAI, or Anthropic. Good for fully local setups with Ollama.

Switch anytime in settings or config.

Tool System Architecture

Memory System

File-based Memory (Default)

Stores memories as readable markdown in ~/.Mudabbir/memory/:

MEMORY.md: Long-term facts about you
sessions/: Conversation history with smart compaction

Session Compaction

Long conversations are automatically compacted to stay within budget:

Recent messages kept verbatim (configurable window)
Older messages compressed to one-liner extracts (Tier 1) or LLM summaries (Tier 2, opt-in)

USER.md Profile

Mudabbir creates identity files at ~/.Mudabbir/identity/ including USER.md, a profile loaded into every conversation so the agent knows your preferences.

Optional: Mem0 (Semantic Memory)

For smarter memory with vector search and automatic fact extraction:

pip install Mudabbir[memory]

See Memory documentation for details.

Configuration

Config lives in ~/.Mudabbir/config.json. API keys and tokens are automatically encrypted in secrets.enc, never stored as plain text.

{
  "agent_backend": "claude_agent_sdk",
  "claude_sdk_model": "",
  "claude_sdk_max_turns": 25,
  "anthropic_api_key": "sk-ant-...",
  "anthropic_model": "claude-sonnet-4-5-20250929",
  "tool_profile": "full",
  "oi_deterministic_desktop_first": true,
  "oi_ai_desktop_planner": true,
  "memory_backend": "file",
  "smart_routing_enabled": false,
  "plan_mode": false,
  "injection_scan_enabled": true,
  "self_audit_enabled": true,
  "web_search_provider": "tavily",
  "tts_provider": "openai"
}

Or use environment variables (all prefixed with MUDABBIR_):

# Core
export MUDABBIR_ANTHROPIC_API_KEY="sk-ant-..."
export MUDABBIR_AGENT_BACKEND="claude_agent_sdk"

# Channels
export MUDABBIR_DISCORD_BOT_TOKEN="..."
export MUDABBIR_SLACK_BOT_TOKEN="xoxb-..."
export MUDABBIR_SLACK_APP_TOKEN="xapp-..."

# Integrations
export MUDABBIR_GOOGLE_OAUTH_CLIENT_ID="..."
export MUDABBIR_GOOGLE_OAUTH_CLIENT_SECRET="..."
export MUDABBIR_TAVILY_API_KEY="..."
export MUDABBIR_GOOGLE_API_KEY="..."

See the full configuration reference for all available settings.

Security

Guardian AI. A secondary LLM reviews every shell command before execution and decides if it's safe.
Injection Scanner. Two-tier detection (regex heuristics + optional LLM deep scan) blocks prompt injection attacks.
Tool Policy. Restrict agent tool access with profiles (minimal, coding, full) and allow/deny lists.
Plan Mode. Require human approval before executing shell commands or file edits.
Security Audit CLI. Run mudabbir --security-audit to check 7 aspects (config permissions, API key exposure, audit log, etc.).
Self-Audit Daemon. Daily automated health checks (12 checks) with JSON reports at ~/.Mudabbir/audit_reports/.
Audit Logging. Append-only log at ~/.Mudabbir/audit.jsonl.
Single User Lock. Only authorized users can control the agent.
File Jail. Operations restricted to allowed directories.
Local LLM Option. Use Ollama and nothing phones home.

Detailed security architecture

See Security documentation for details.

Development

# Clone
git clone https://github.com/Ahmed5754/mudabbir.git
cd mudabbir

# Install with dev dependencies
uv sync --dev

# Run the dashboard with auto-reload (watches *.py, *.html, *.js, *.css)
uv run mudabbir --dev

# Run tests
uv run pytest

# Lint
uv run ruff check .

# Format
uv run ruff format .

Optional Extras

pip install Mudabbir[discord]             # Discord support
pip install Mudabbir[slack]               # Slack support
pip install Mudabbir[whatsapp-personal]   # WhatsApp Personal (QR scan)
pip install Mudabbir[image]               # Image generation (Google Gemini)
pip install Mudabbir[memory]             # Mem0 semantic memory
pip install Mudabbir[matrix]              # Matrix support
pip install Mudabbir[teams]               # Microsoft Teams support
pip install Mudabbir[gchat]               # Google Chat support
pip install Mudabbir[mcp]                 # MCP server support
pip install Mudabbir[all]                 # Everything

Documentation

Full documentation lives in documentation/:

Channel Adapters: Discord, Slack, WhatsApp, Telegram setup
Tool Policy: Profiles, groups, allow/deny
Web Dashboard: Browser UI overview
Security: Injection scanner, audit CLI, audit logging
Model Router: Smart complexity-based model selection
Plan Mode: Approval workflow for tool execution
Integrations: OAuth, Gmail, Calendar, Drive, Docs, Spotify
Tools: Web search, research, image gen, voice, delegation, skills
Memory: Session compaction, USER.md profile, Mem0
Scheduler: Cron scheduler, self-audit daemon

License

Made with love for humans who want AI on their own terms

Name		Name	Last commit message	Last commit date
Latest commit History 156 Commits
.github		.github
assets		assets
docs		docs
installer		installer
nginx		nginx
src/Mudabbir		src/Mudabbir
tests		tests
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.python-version		.python-version
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
Dockerfile.docs		Dockerfile.docs
Dockerfile.landing		Dockerfile.landing
LICENSE		LICENSE
Mudabbir.png		Mudabbir.png
README.md		README.md
RUN_WINDOWS_QUICKSTART.md		RUN_WINDOWS_QUICKSTART.md
docker-compose.yml		docker-compose.yml
fly.toml		fly.toml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Mudabbir

Quick Start

Docker

What Can Mudabbir Do?

Examples

Research & Browsing

Coding & DevOps

Multi-Agent Workflows (Mission Control)

Web Dashboard

Channel Management

Browser

Windows Skills Coverage (31-39 + AI)

Deterministic-First Windows Routing

Architecture

Agent Backends

Memory System

File-based Memory (Default)

Session Compaction

USER.md Profile

Optional: Mem0 (Semantic Memory)

Configuration

Security

Development

Optional Extras

Documentation

Follow us

License

About

Uh oh!

Releases 12

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Mudabbir

Quick Start

Docker

What Can Mudabbir Do?

Examples

Research & Browsing

Coding & DevOps

Multi-Agent Workflows (Mission Control)

Web Dashboard

Channel Management

Browser

Windows Skills Coverage (31-39 + AI)

Deterministic-First Windows Routing

Architecture

Agent Backends

Memory System

File-based Memory (Default)

Session Compaction

USER.md Profile

Optional: Mem0 (Semantic Memory)

Configuration

Security

Development

Optional Extras

Documentation

Follow us

License

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 12

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages