Metadata-Version: 2.4
Name: prowlrbot
Version: 1.0.0
Summary: ProwlrBot — Always watching. Always ready. An autonomous AI agent platform for monitoring, automation, and multi-channel communication.
Author-email: kdairatchi <kdairatchi@users.noreply.github.com>
License: Apache-2.0
Requires-Python: <3.15,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: prowlr-agentscope>=1.0.16
Requires-Dist: prowlr-agentscope-runtime>=1.1.0
Requires-Dist: cryptography>=46.0.5
Requires-Dist: pynacl>=1.5.0
Requires-Dist: discord-py>=2.7.1
Requires-Dist: dingtalk-stream>=0.24.3
Requires-Dist: uvicorn>=0.41.0
Requires-Dist: apscheduler<4,>=3.11.2
Requires-Dist: playwright>=1.58.0
Requires-Dist: questionary>=2.1.1
Requires-Dist: mss>=10.1.0
Requires-Dist: reme-ai==0.3.0.5
Requires-Dist: transformers>=4.49.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-socks>=2.8.1
Requires-Dist: onnxruntime<1.25
Requires-Dist: lark-oapi>=1.5.3
Requires-Dist: python-telegram-bot>=22.7
Requires-Dist: httpx>=0.28.1
Requires-Dist: slowapi>=0.1.9
Requires-Dist: requests>=2.32.4
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: python-multipart>=0.0.22
Requires-Dist: sentry-sdk[fastapi]>=2.0
Requires-Dist: stripe>=11.0.0
Requires-Dist: jmespath>=1.0
Requires-Dist: pyjwt[crypto]>=2.10
Requires-Dist: numpy>=1.24
Requires-Dist: psutil>=5.9
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.3.1; extra == "dev"
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Requires-Dist: pytest-cov>=7.0.0; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Provides-Extra: local
Requires-Dist: huggingface_hub>=1.6.0; extra == "local"
Provides-Extra: llamacpp
Requires-Dist: prowlrbot[local]; extra == "llamacpp"
Requires-Dist: llama-cpp-python>=0.3.0; extra == "llamacpp"
Provides-Extra: mlx
Requires-Dist: prowlrbot[local]; extra == "mlx"
Requires-Dist: mlx-lm>=0.10.0; extra == "mlx"
Provides-Extra: ollama
Requires-Dist: ollama>=0.6.1; extra == "ollama"
Provides-Extra: slack
Requires-Dist: slack-bolt>=1.18.0; extra == "slack"
Requires-Dist: slack-sdk>=3.27.0; extra == "slack"
Provides-Extra: doctor
Requires-Dist: prowlr-doctor>=0.1; extra == "doctor"
Provides-Extra: nacos
Requires-Dist: nacos-sdk-python>=3.0.0; extra == "nacos"
Requires-Dist: cryptography>=46.0.5; extra == "nacos"
Provides-Extra: desktop
Requires-Dist: pystray>=0.19; extra == "desktop"
Requires-Dist: plyer>=2.1; extra == "desktop"
Requires-Dist: Pillow>=10.0; extra == "desktop"
Provides-Extra: swarm
Requires-Dist: redis>=5.0; extra == "swarm"
Provides-Extra: backup-s3
Requires-Dist: boto3>=1.34; extra == "backup-s3"
Dynamic: license-file

<p align="center">
  <img src="/console/public/logo.png" alt="ProwlrBot Logo" width="400" />
</p>

<h1 align="center">ProwlrBot</h1>

<p align="center">
  <em>Always watching. Always ready.</em><br>
  <strong>Your AI agent. Your machine. Your rules.</strong>
</p>

<p align="center">
  <a href="#-get-started-in-60-seconds"><b>Quick Start</b></a> &bull;
  <a href="#-what-it-looks-like"><b>Screenshots</b></a> &bull;
  <a href="docs/README.md"><b>Docs</b></a> &bull;
  <a href="https://github.com/ProwlrBot/prowlr-marketplace"><b>Marketplace</b></a> &bull;
  <a href="#-roar-protocol"><b>ROAR Protocol</b></a> &bull;
  <a href="https://github.com/sponsors/kdairatchi"><b>Sponsor</b></a>
</p>

<p align="center">
  <img src="https://img.shields.io/github/stars/ProwlrBot/prowlrbot?style=flat-square&logo=github" alt="Stars">
  <img src="https://img.shields.io/github/license/ProwlrBot/prowlrbot?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/python-3.10--3.13-blue?style=flat-square&logo=python" alt="Python">
  <img src="https://img.shields.io/badge/self--hosted-first-brightgreen?style=flat-square" alt="Self-hosted">
  <img src="https://img.shields.io/badge/local%20models-Ollama%20%7C%20llama.cpp%20%7C%20MLX-blue?style=flat-square" alt="Local models">
  <img src="https://img.shields.io/badge/channels-9%2B-purple?style=flat-square" alt="Channels">
  <img src="https://img.shields.io/badge/v1.0.0-released-brightgreen?style=flat-square" alt="v1.0.0">
</p>

---

ProwlrBot is a **self-hosted AI agent platform** that runs on your machine, connects to every channel you use, and keeps working while you sleep.

It monitors websites for changes. It runs scheduled tasks. It answers your team on Discord, Telegram, Slack, and WhatsApp at the same time. It coordinates multiple AI agents in a War Room so they don't step on each other. It does all of this with **your API keys, your models, your data — nothing leaves your network unless you want it to.**

No subscription. No vendor lock-in. Install and own it forever.

```bash
pip install prowlrbot && prowlr init --defaults && prowlr app
```

---

## What It Looks Like

<table>
<tr>
<td width="50%">

**Mission Control Dashboard**
<img src="/console/public/demo/dashboard.png" alt="Dashboard" width="100%">
<em>Real-time overview of your agent, channels, and system health</em>

</td>
<td width="50%">

**Chat Interface**
<img src="/console/public/demo/chat.png" alt="Chat" width="100%">
<em>Talk to your agent with full tool use, code execution, and file handling</em>

</td>
</tr>
<tr>
<td width="50%">

**Skills Marketplace**
<img src="/console/public/demo/marketplace.png" alt="Marketplace" width="100%">
<em>Browse, install, and publish skills — PDF processing, email, monitoring, and more</em>

</td>
</tr>
<tr>
<td width="50%">

**Web Monitoring**
<img src="/console/public/demo/monitoring.png" alt="Monitoring" width="100%">
<em>Watch websites and APIs for changes — get alerted when something moves</em>

</td>
<td width="50%">

**MCP Server Integration**
<img src="/console/public/demo/mcp.png" alt="MCP Servers" width="100%">
<em>Connect any MCP server — tools appear instantly with hot-reload</em>

</td>
</tr>
<tr>
<td width="50%">

**Channel Management**
<img src="/console/public/demo/channels.png" alt="Channels" width="100%">
<em>Discord, Telegram, Slack, WhatsApp, DingTalk, Feishu, iMessage — all at once</em>

</td>
<td width="50%">

**Team Builder**
<img src="/console/public/demo/team-builder.png" alt="Team Builder" width="100%">
<em>Design multi-agent teams with specialized roles and capabilities</em>

</td>
</tr>
</table>

<details>
<summary><strong>More screenshots</strong></summary>
<table>
<tr>
<td><img src="/console/public/demo/skills.png" alt="Skills" width="100%"><br><em>Skills Manager</em></td>
<td><img src="/console/public/demo/workspace.png" alt="Workspace" width="100%"><br><em>Agent Workspace</em></td>
</tr>
<tr>
<td><img src="/console/public/demo/cron-jobs.png" alt="Cron Jobs" width="100%"><br><em>Scheduled Tasks</em></td>
<td><img src="/console/public/demo/appearance.png" alt="Appearance" width="100%"><br><em>Theme Customization</em></td>
</tr>
<tr>
<td><img src="/console/public/demo/hardware.png" alt="Hardware Advisor" width="100%"><br><em>Hardware Advisor</em></td>
<td></td>
</tr>
</table>
</details>

---

## Why ProwlrBot?

There are a lot of AI chatbots. ProwlrBot is not a chatbot. **It's an agent that acts.**

| The old way | With ProwlrBot |
|-------------|----------------|
| Check 10 tabs manually every morning | Agent monitors all of them, pings you only when something changes |
| Forget to follow up on something | Schedule it once — the agent handles it at 9am every day |
| Three Claude terminals stepping on each other | War Room coordinates them — file locks, shared task board, zero conflicts |
| Paying $50/mo for a tool that phones home | Self-hosted, model-agnostic, free forever |
| Building separate bots for Discord + Telegram + Slack | One agent, all channels, same brain |

### Core Principles

- **Your data stays yours.** API keys are encrypted locally. Chat history lives on your machine. Run entirely on local models with Ollama — no API key, no data leaving your network.
- **It speaks where you already are.** One agent, 8+ channels. Discord, Telegram, Slack, WhatsApp, DingTalk, Feishu, iMessage, Console. Custom channels too.
- **It grows with you.** Skill marketplace for adding capabilities. ROAR Protocol for agent-to-agent communication across machines and organizations.

---

## Get Started in 60 Seconds

```bash
# 1. Install
pip install prowlrbot

# 2. Initialize (auto-detects local models)
prowlr init --defaults

# 3. Set an API key (optional — skip if using Ollama)
prowlr env set OPENAI_API_KEY sk-your-key

# 4. Launch
prowlr app
```

Open **http://localhost:8088** — your agent is live.

> **No API key?** ProwlrBot auto-detects Ollama. Just `prowlr init --defaults && prowlr app`.

<details>
<summary><strong>Install from source (development)</strong></summary>

```bash
git clone https://github.com/ProwlrBot/prowlrbot.git
cd prowlrbot
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
prowlr init --defaults
prowlr app
```

</details>

<details>
<summary><strong>Docker</strong></summary>

```bash
docker pull ghcr.io/prowlrbot/prowlrbot:latest
docker run -p 8088:8088 -v ~/.prowlrbot:/root/.prowlrbot ghcr.io/prowlrbot/prowlrbot:latest
```

</details>

<details>
<summary><strong>Desktop App (macOS / Windows / Linux)</strong></summary>

Download from [GitHub Releases](https://github.com/ProwlrBot/prowlrbot/releases) or build yourself:

```bash
# macOS (.app + DMG)
bash packaging/build_macos.sh

# Windows (.exe)
powershell -File packaging/build_windows.ps1

# Linux (binary + AppImage)
bash packaging/build_linux.sh --appimage
```

System tray app with one-click launch. [Full guide →](docs/guides/desktop-build.md)

</details>

<details>
<summary><strong>WSL notes</strong></summary>

- Clone to `/home/user/prowlrbot`, **not** `/mnt/c/...`
- Create venv inside the project: `python3 -m venv .venv`
- See [Troubleshooting Guide](docs/troubleshooting.md) for WSL-specific issues

</details>

---

## Architecture

```
                    YOU
                     │
          ┌──────────┼──────────┐
          ▼          ▼          ▼
      Discord    Telegram    Slack       + 6 more channels
          │          │          │
          └──────────┼──────────┘
                     ▼
             ChannelManager              queue + debounce (4 workers/channel)
                     │
                     ▼
              AgentRunner                session management
                     │
                     ▼
           ProwlrBotAgent (ReAct)        reasoning loop
            ┌────┬────┬────┬────┐
            ▼    ▼    ▼    ▼    ▼
         Tools Skills MCP Memory ROAR    capabilities
            │    │    │    │    │
            └────┼────┼────┼────┘
                 ▼    ▼    ▼
         ┌───────────────────────┐
         │     Smart Router      │       cost × w₁ + speed × w₂ + avail × w₃
         ├───────────────────────┤
         │ OpenAI  │ Anthropic   │
         │ Groq    │ Z.ai        │
         │ Ollama  │ llama.cpp   │
         │ MLX     │ Azure       │
         └───────────────────────┘
                     │
                     ▼
              ChatManager                persistence (chats + sessions)
```

**Provider detection flow:**

```
Environment Scan → ProviderDetector (env vars) → HealthChecker (async probes)
→ SmartRouter (score = w_cost × cost + w_perf × perf + w_avail × avail)
→ Selected Provider → FallbackChain on failure
```

---

## Features

### Multi-Agent War Room

The killer feature: multiple AI agents coordinate in real-time without stepping on each other.

```
╔══════════════════════════════════════════════════════════════╗
║                      MISSION BOARD                          ║
╠════╦══════════════════════╦═══════════╦══════════════════════╣
║ ID ║ Task                 ║ Agent     ║ Status               ║
╠════╬══════════════════════╬═══════════╬══════════════════════╣
║  1 ║ Build auth API       ║ backend   ║ In Progress          ║
║  2 ║ Login page           ║ frontend  ║ In Progress          ║
║  3 ║ Write auth tests     ║ tester    ║ Waiting (locked)     ║
║  4 ║ API documentation    ║ --        ║ Available            ║
╚════╩══════════════════════╩═══════════╩══════════════════════╝
```

**13 coordination tools** — `check_mission_board`, `claim_task`, `lock_file`, `share_finding`, and more.

<details>
<summary><strong>Quick War Room setup</strong></summary>

```bash
# 1. Start the hub
cd prowlrbot && PYTHONPATH=src python3 -m prowlrbot.hub.bridge

# 2. In your project's .mcp.json:
{
  "mcpServers": {
    "prowlr-hub": {
      "command": "python3",
      "args": ["-m", "prowlrbot.hub"],
      "cwd": "/path/to/prowlrbot",
      "env": {
        "PYTHONPATH": "/path/to/prowlrbot/src",
        "PROWLR_AGENT_NAME": "frontend",
        "PROWLR_CAPABILITIES": "react,typescript,css"
      }
    }
  }
}

# 3. Restart Claude Code, then:
# "Call check_mission_board and get_agents to see the War Room."
```

Cross-machine support via HTTP bridge + Tailscale/Cloudflare. [Full guide →](docs/guides/cross-network-setup.md)

</details>

---

### Smart Model Router

Automatically picks the best provider based on scoring:

```
score = cost × w₁ + speed × w₂ + availability × w₃
```

| Provider | How to Enable | Cost |
|----------|---------------|------|
| OpenAI | `OPENAI_API_KEY` | $$ |
| Anthropic | `ANTHROPIC_API_KEY` | $$ |
| Groq | `GROQ_API_KEY` | $ |
| Z.ai | `ZAI_API_KEY` | $$ |
| Ollama | Auto-detected locally | Free |
| llama.cpp | `pip install 'prowlrbot[llamacpp]'` | Free |
| MLX | `pip install 'prowlrbot[mlx]'` (Apple Silicon) | Free |

Falls back automatically if a provider fails. Zero config needed — just set the API key and ProwlrBot finds it.

---

### 9+ Communication Channels

<table>
<tr>
<td align="center"><strong>Discord</strong><br>Built-in</td>
<td align="center"><strong>Telegram</strong><br>Built-in</td>
<td align="center"><strong>Slack</strong><br><a href="docs/guides/slack-setup.md">Setup guide</a></td>
<td align="center"><strong>WhatsApp</strong><br><a href="docs/guides/whatsapp-setup.md">Setup guide</a></td>
</tr>
<tr>
<td align="center"><strong>DingTalk</strong><br>Built-in</td>
<td align="center"><strong>Feishu/Lark</strong><br>Built-in</td>
<td align="center"><strong>QQ</strong><br>Built-in</td>
<td align="center"><strong>iMessage</strong><br>macOS only</td>
</tr>
<tr>
<td align="center"><strong>Console</strong><br>Default</td>
<td align="center" colspan="3"><em>Custom channels via <code>~/.prowlrbot/custom_channels/</code></em></td>
</tr>
</table>

One agent brain, all channels simultaneously. Build custom channels for anything else. [Channel guide →](docs/guides/channels.md)

---

### Skills Marketplace

<img src="/console/public/demo/marketplace.png" alt="Marketplace" width="600">

Browse, install, and publish skills that extend your agent:

```bash
prowlr market search "monitor"       # Find skills
prowlr market install site-monitor   # Install one
prowlr market seed                   # Load all official listings + bundles
```

**11 official listings** — morning briefing, smart reminders, site monitor, competitor watch, invoice chaser, and more. **6 curated bundles** — Security Starter, Full-Stack Dev, Data & Analytics, Document Pro, Daily Essentials, Business Ops.

Submit your own skills through the console UI or CLI. [Marketplace guide →](docs/guides/marketplace.md)

---

### Web Monitoring & Cron Jobs

```bash
# Monitor a website for changes
prowlr monitor add https://example.com/pricing --interval 1h

# Schedule an autonomous agent task
prowlr cron add "Check email and summarize" --schedule "0 9 * * *"
prowlr cron add "Monitor competitors" --interval 30m
```

<img src="/console/public/demo/monitoring.png" alt="Monitoring" width="600">

---

### ROAR Protocol

**One protocol. Any agent.** ProwlrBot speaks [ROAR](docs/protocols/roar-spec-v1.0.md) — the open agent communication protocol that bridges MCP, A2A, and ACP.

```
Layer 5: Stream     Real-time events (SSE, WebSocket)
Layer 4: Exchange   ROARMessage — 7 intent types, HMAC signing
Layer 3: Connect    HTTP | WebSocket | stdio | gRPC
Layer 2: Discovery  Hub + Cache + SQLite directory
Layer 1: Identity   W3C DIDs (did:roar, did:key, did:web)
```

```bash
# Check any ROAR agent
curl -s https://app.prowlrbot.com/roar/health
curl -s https://app.prowlrbot.com/roar/card | jq .
```

<details>
<summary><strong>ROAR examples</strong></summary>

```python
# Send a task to another agent
from prowlrbot.protocols.sdk import AgentIdentity, MessageIntent
from prowlrbot.protocols.sdk.client import ROARClient

identity = AgentIdentity(display_name="my-agent", capabilities=["code-review"])
client = ROARClient(identity, signing_secret=os.environ["ROAR_SHARED_SECRET"])

response = await client.send_remote(
    to_agent_id="did:roar:agent:reviewer-abc123",
    intent=MessageIntent.DELEGATE,
    content={"task": "Review main.py"},
)
```

Three runnable examples in [`examples/roar/`](examples/roar/):
1. **Basic message exchange** — sign, send, verify
2. **MCP bridge** — translate MCP tool calls through ROAR
3. **Multi-agent delegation** — coordinator discovers and delegates to specialized agents

</details>

[Live Demo →](https://roar.prowlrbot.com) &bull; [ROAR Spec →](docs/protocols/roar-spec-v1.0.md) &bull; [Usage Guide →](docs/guides/roar-usage.md) &bull; [PyPI Package →](https://pypi.org/project/roar-protocol/)

---

### v1.0.0 — What's New

<details>
<summary><strong>35 features shipped in v1.0.0</strong></summary>

**Security & Trust**
- Fine-grained tool permissions with command blocklist and file sandboxing
- Agent safety guardrails — loop detection, token budgets, exponential backoff
- Cost dashboard with real-time tracking, budget limits, and model fallback
- Automated security audit (`GET /api/health/security-audit`) covering OWASP Top 10
- 23 security vulnerabilities found and fixed across the codebase

**Intelligence**
- Vector-based semantic memory search with local ONNX embeddings
- RAG pipeline — ingest PDF, DOCX, TXT, code files with intelligent chunking
- Agent templates — 11 pre-built personas (DevOps, SRE, Research, Community Manager, etc.)
- Memory visualization API — timeline, stats, semantic search, compaction

**Automation**
- Webhook gateway — receive triggers from GitHub, Stripe, or any HTTP source
- Advanced web monitor — visual diff engine with smart alert filtering
- Huginn & n8n migration toolkit — `prowlr import-from` CLI

**Infrastructure**
- Docker Compose one-click production stack
- Desktop app packaging (macOS DMG, Windows EXE, Linux AppImage)
- Plugin & middleware extension system
- A2A protocol client for cross-agent task delegation

**Console UI**
- Mission Control redesign with StatusBar, CommandPalette (Ctrl+K), ContextPanel
- Cost dashboard, trace viewer, health dashboard pages
- Responsive mobile PWA with bottom tab bar
- Onboarding setup wizard for first-run experience

**AgentVerse** — [standalone app](https://github.com/ProwlrBot/agentverse)
- Gamified agent coordination — zones, avatars, XP, guilds, arena, trades
- Real-time WebSocket updates with prowlr-office design system
- Connects to any ProwlrBot instance via `PROWLRBOT_URL`

[Full changelog →](CHANGELOG.md)

</details>

---

### Security

ProwlrBot is built with a security-first posture:

- **JWT authentication** — all API endpoints require a signed JWT. Tokens are issued on login and validated on every request via FastAPI middleware.
- **RBAC** — four roles enforced at the route level: `admin` (full access), `operator` (run agents, manage channels/cron), `viewer` (read-only), `agent` (machine-to-machine, limited to task and finding endpoints).
- **CSRF protection** — double-submit cookie pattern applied to all state-mutating endpoints.
- **Rate limiting** — per-IP and per-user limits on the API to prevent abuse.
- **Secret isolation** — API keys and tokens are stored in `~/.prowlrbot.secret/envs.json` (mode 0o600), never in the main config file.
- **Bandit scan** — automated static analysis runs in CI. Current result: **0 high-severity issues**.
- **Security audit endpoint** — `GET /api/health/security-audit` checks OWASP Top 10 coverage at runtime.

---

### MCP Integration

Connect any Model Context Protocol server — tools appear instantly with hot-reload:

```json
{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
      }
    }
  }
}
```

<img src="/console/public/demo/mcp.png" alt="MCP" width="600">

---

### Local Models (No Cloud Required)

Run everything on your machine. No API keys. No data leaving your computer.

| Backend | Best For | Install |
|---------|----------|---------|
| **Ollama** | Cross-platform, easiest | [ollama.ai](https://ollama.ai) |
| **llama.cpp** | GGUF models, CPU/GPU | `pip install 'prowlrbot[llamacpp]'` |
| **MLX** | Apple Silicon (M1-M4) | `pip install 'prowlrbot[mlx]'` |

ProwlrBot auto-detects Ollama on startup. No configuration needed.

---

### Desktop App

Native system tray app for macOS, Windows, and Linux. One click to launch, no terminal required.

```bash
# Build for your platform
bash packaging/build_macos.sh      # .app + DMG
powershell packaging/build_windows.ps1  # .exe
bash packaging/build_linux.sh --appimage  # AppImage
```

Purple circle = idle. Green = active. Red = error. [Build guide →](docs/guides/desktop-build.md)

---

## Project Structure

```
prowlrbot/
├── src/prowlrbot/
│   ├── agents/              # ReAct agent, tools, skills, memory
│   ├── app/                 # FastAPI app, channels, cron, MCP, routers
│   ├── cli/                 # Click CLI (`prowlr` command)
│   ├── config/              # Pydantic models + hot-reload
│   ├── providers/           # Model registry, detector, smart router
│   ├── protocols/           # ROAR protocol SDK + A2A server + client
│   ├── marketplace/         # Skill marketplace store + seed data
│   ├── monitor/             # Web/API change detection + visual diff
│   ├── rag/                 # RAG pipeline — ingest, chunk, retrieve
│   ├── webhooks/            # Webhook gateway — triggers + actions
│   ├── agentverse/          # AgentVerse world state + event hooks
│   ├── security/            # Audit reports + middleware
│   ├── desktop/             # System tray launcher (PyInstaller)
│   ├── migrate/             # Huginn + n8n import tools
│   ├── backup/              # Conversation backup engine
│   ├── workflows/           # Visual automation engine
│   ├── plugins/             # Plugin lifecycle + middleware
│   ├── hub/                 # ProwlrHub war room (MCP server)
│   └── envs/                # Encrypted secret store
├── console/                 # React 18 + Vite + Ant Design dashboard
├── packages/roar-sdk-ts/    # TypeScript ROAR SDK
├── marketplace-listings/    # 11 official skill listings
├── examples/roar/           # ROAR protocol examples
├── packaging/               # Desktop build scripts (macOS/Win/Linux)
├── swarm/                   # Cross-machine Redis execution
├── plugins/                 # Claude Code plugins
├── docs/                    # Documentation hub
│   ├── guides/              # Setup, channels, desktop, marketplace
│   ├── protocols/           # ROAR spec + layer docs
│   └── blog/                # Project blog
└── website/                 # GitHub Pages docs site
```

---

## Documentation

| Guide | What You'll Learn |
|-------|------------------|
| [Channel Setup](docs/guides/channels.md) | Connect Discord, Telegram, DingTalk, Feishu, iMessage, QQ |
| [Slack Setup](docs/guides/slack-setup.md) | Custom channel with Slack Bolt + Socket Mode |
| [WhatsApp Setup](docs/guides/whatsapp-setup.md) | WhatsApp Business Cloud API + webhooks |
| [Provider Config](docs/guides/providers.md) | OpenAI, Anthropic, Groq, Ollama, local models |
| [Skills Guide](docs/guides/skills.md) | Enable, create, and publish skills |
| [MCP Setup](docs/guides/mcp-setup.md) | Connect filesystem, GitHub, Postgres MCP servers |
| [Marketplace](docs/guides/marketplace.md) | Browse, install, publish, credits system |
| [Monitoring](docs/guides/monitoring.md) | Watch websites and APIs for changes |
| [Cron Jobs](docs/guides/cron-jobs.md) | Schedule autonomous agent tasks |
| [Desktop Build](docs/guides/desktop-build.md) | Build DMG/EXE/AppImage desktop app |
| [Deployment](docs/guides/deployment.md) | Docker, Fly.io, systemd, nginx |
| [ROAR Protocol](docs/protocols/roar-spec-v1.0.md) | Agent communication spec — identity, discovery, streaming |
| [Cross-Network](docs/guides/cross-network-setup.md) | Connect agents across machines |
| [Memory System](docs/guides/memory-system.md) | Tiered memory, vector search, RAG |
| [CLI Reference](docs/guides/cli-reference.md) | Every command, every flag |
| [Troubleshooting](docs/troubleshooting.md) | WSL, pip, ports, MCP, console fixes |

[Full docs index →](docs/README.md)

---

## Ecosystem

| Project | Description |
|---------|-------------|
| [**ProwlrBot**](https://github.com/ProwlrBot/prowlrbot) | Core agent platform (you are here) |
| [**ROAR Protocol**](https://github.com/ProwlrBot/roar-protocol) | Agent communication standard — `pip install roar-protocol` |
| [**Marketplace**](https://github.com/ProwlrBot/prowlr-marketplace) | Skills & agents marketplace |
| [**AgentVerse**](https://github.com/ProwlrBot/agentverse) | Gamified agent world — zones, avatars, XP, guilds, arena |
| [**prowlr-office**](https://github.com/ProwlrBot/prowlr-office) | Collaborative workspace for humans + AI agents (coming soon) |
| [**Docs**](https://github.com/ProwlrBot/prowlr-docs) | Centralized documentation |

---

## Testing

The test suite uses pytest with pytest-asyncio (`asyncio_mode = "auto"`). **1,085 tests** currently pass.

```bash
pytest                          # full suite
pytest -m "not slow"           # skip integration/slow tests
pytest tests/test_react_agent_tool_choice.py  # single file
```

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for commit conventions and PR guidelines.

<a href="https://github.com/ProwlrBot/prowlrbot/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=ProwlrBot/prowlrbot" />
</a>

**Good first ways to get involved:**

- Star the repo — helps more people find the project
- [Open an issue](https://github.com/ProwlrBot/prowlrbot/issues) — bugs, questions, ideas
- [Start a discussion](https://github.com/ProwlrBot/prowlrbot/discussions) — share your setup, ask how something works
- [Build a skill](docs/guides/skills.md) — publish it to the marketplace
- Tell someone — word of mouth is the fastest way to grow

---

## Support the Project

ProwlrBot is free, open source, and will stay that way. If it saves you time, consider sponsoring.

<p align="center">
  <a href="https://github.com/sponsors/kdairatchi">
    <img src="https://img.shields.io/badge/GitHub_Sponsors-Sponsor-EA4AAA?style=for-the-badge&logo=github-sponsors&logoColor=white" alt="GitHub Sponsors" />
  </a>
  &nbsp;
  <a href="https://buymeacoffee.com/kdairatchi">
    <img src="https://img.shields.io/badge/Buy_Me_a_Coffee-Support-FFDD00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee" />
  </a>
  &nbsp;
  <a href="https://ko-fi.com/kdairatchi">
    <img src="https://img.shields.io/badge/Ko--fi-Donate-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Ko-fi" />
  </a>
  &nbsp;
  <a href="https://opencollective.com/prowlrbot">
    <img src="https://img.shields.io/badge/Open_Collective-Contribute-3295A8?style=for-the-badge&logo=opencollective&logoColor=white" alt="Open Collective" />
  </a>
</p>

---

## License

ProwlrBot is open source under the [Apache 2.0 License](LICENSE).

---

<p align="center">
  <strong>ProwlrBot</strong> — Always watching. Always ready.<br>
  Built by <a href="https://github.com/kdairatchi">kdairatchi</a><br><br>
  <a href="docs/README.md">Docs</a> &bull;
  <a href="docs/blog/">Blog</a> &bull;
  <a href="https://github.com/ProwlrBot/prowlrbot/discussions">Discussions</a> &bull;
  <a href="https://github.com/ProwlrBot/prowlrbot/issues">Issues</a> &bull;
  <a href="https://github.com/ProwlrBot/prowlr-marketplace">Marketplace</a> &bull;
  <a href="CONTRIBUTING.md">Contribute</a> &bull;
  <a href="https://github.com/sponsors/kdairatchi">Sponsor</a>
</p>
