catpaw

English | 中文

🐾 catpaw

catpaw is a lightweight monitoring agent with AI-powered diagnostics. It detects anomalies through plugin-based checks, produces standardized events, and — when an alert fires — can automatically trigger AI root-cause analysis using 70+ built-in diagnostic tools.

Events can be forwarded to any alert platform (Flashduty, PagerDuty, or any HTTP endpoint), or simply printed to the console for quick validation.

✨ Key Features

• 🪶 Lightweight, zero heavy dependencies — single binary, easy to deploy
• 🔌 Plugin-based monitoring — 25+ check plugins, enable only what you need
• 🤖 AI-powered diagnosis — automatic root-cause analysis triggered by alerts
• 💬 Interactive AI chat — troubleshoot issues conversationally with AI + tools
• 🩺 Proactive health inspection — on-demand AI-driven health checks
• 🛠️ 70+ diagnostic tools — system, network, storage, security, process, kernel
• 🔗 MCP integration — connect external data sources (Prometheus, Jaeger, CMDB, etc.) via Model Context Protocol
• 📡 Flexible notification — console, generic WebAPI, Flashduty, PagerDuty, or any combination
• 🔄 Self-monitoring friendly — ideal for monitoring your monitoring systems

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                        catpaw agent                             │
│                                                                 │
│  ┌─────────────┐   alert    ┌──────────────┐    AI + Tools     │
│  │  25+ Check  │ ────────── │  AI Diagnose │ ──────────────┐   │
│  │   Plugins   │  trigger   │    Engine    │               │   │
│  └──────┬──────┘            └──────────────┘               │   │
│         │                                                  ▼   │
│         │ events    ┌──────────────┐         ┌───────────────┐ │
│         └────────── │   Notifiers  │         │  70+ Diagnose │ │
│                     │  (multiple)  │         │     Tools     │ │
│                     └──────────────┘         └───────┬───────┘ │
│                                                      │         │
│  ┌─────────────┐                            ┌────────┴───────┐ │
│  │  AI Chat    │ ───── interactive ──────── │  MCP External  │ │
│  │  (CLI)      │       troubleshoot         │  Data Sources  │ │
│  └─────────────┘                            └────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

🔍 Check Plugins

🧠 AI Diagnostic Tools (70+)

When AI diagnosis is triggered (by alert, inspection, or chat), the AI agent has access to a rich toolkit:

⚙️ System & Process: CPU top, memory breakdown, OOM history, cgroup limits, process threads (with wchan), open files, environment variables, PSI pressure

🌐 Network: ping, traceroute, DNS resolve, ARP neighbors, TCP connection states, socket details (RTT/cwnd), retransmission rate, connection latency summary, listen queue overflow, TCP tuning check, softnet stats, route table, IP addresses, interface stats, firewall rules

💾 Storage: disk I/O latency, block device topology, LVM status, mount info

🔐 Kernel & Security: dmesg, interrupts distribution, conntrack stats, NUMA stats, thermal zones, sysctl snapshot, SELinux/AppArmor status, coredump list

📜 Logs: log tail, log grep (with pattern matching), journald query

🐳 Services: systemd service status, failed services list, timer list, Docker ps/inspect

🔌 Remote plugins (Redis, etc.) contribute their own specialized diagnostic tools for deep introspection.

🔗 MCP external tools: Connect Prometheus, Jaeger, CMDB, or any MCP-compatible data source — the AI automatically discovers and uses their tools.

🖥️ CLI Commands

catpaw run [flags]                      # Start the monitoring agent
catpaw chat [-v]                        # Interactive AI chat for troubleshooting
catpaw inspect <plugin> [target]        # Proactive AI health inspection
catpaw diagnose list|show <id>          # View past diagnosis records
catpaw selftest [filter] [-q]           # Smoke-test all diagnostic tools
catpaw mcptest                          # Test MCP server connections

🚀 Quick Start

📦 Installation

Download the binary from GitHub Releases.

Basic Monitoring

1. Enable plugin configs under conf.d/p.<plugin>/
2. Start:

./catpaw run

The default config enables [notify.console], so events are printed to the terminal with colored output — no external service needed for a quick test.

📡 Event Notification

catpaw supports multiple notification channels. Configure one or more in conf.d/config.toml:

Multiple channels can be active simultaneously. For example, you can print to console for debugging while also forwarding to your alert platform.

Console (default — for quick validation):

[notify.console]
enabled = true

WebAPI (push raw Event JSON to any HTTP endpoint):

[notify.webapi]
url = "https://your-service.example.com/api/v1/events"
# method = "POST"
# timeout = "10s"
[notify.webapi.headers]
Authorization = "Bearer ${WEBAPI_TOKEN}"

Flashduty:

[notify.flashduty]
integration_key = "your-integration-key"

PagerDuty:

[notify.pagerduty]
routing_key = "your-routing-key"

🤖 AI Diagnosis (optional)

Add to conf.d/config.toml:

[ai]
enabled = true
model_priority = ["default"]

[ai.models.default]
base_url = "https://api.openai.com/v1"
api_key = "${OPENAI_API_KEY}"
model = "gpt-4o"

Now when alerts fire, AI automatically analyzes root cause using built-in diagnostic tools.

💬 Interactive Chat

./catpaw chat

Ask questions like "Why is CPU high?" or "Check disk I/O latency" — the AI uses diagnostic tools and shell commands (with confirmation) to investigate.

🔗 MCP External Data Sources (optional)

Connect Prometheus, Jaeger, or other MCP servers for AI to query historical metrics, traces, etc.:

[ai.mcp]
enabled = true

[[ai.mcp.servers]]
name = "prometheus"
command = "/usr/local/bin/mcp-prometheus"
args = ["serve"]
identity = 'instance="${IP}:9100"'
[ai.mcp.servers.env]
PROMETHEUS_URL = "http://127.0.0.1:9090"

[[ai.mcp.servers]]
name = "nightingale"
command = "npx"
args = ["-y", "@n9e/n9e-mcp-server", "stdio"]
identity = 'ident="${HOSTNAME}"'
tools_allow = []
[ai.mcp.servers.env]
N9E_TOKEN = "480c04ed-ebe7-4266-xxxx-f8daf7819a6d"
N9E_BASE_URL = "http://127.0.0.1:17000"

Verify connectivity:

./catpaw mcptest

⚙️ Configuration

• Global config: conf.d/config.toml
• Plugin configs: conf.d/p.<plugin>/*.toml (multiple files merged on load)
• Hot-reload plugin configs with SIGHUP:

kill -HUP $(pidof catpaw)

📚 Documentation

💬 Community

WeChat: add picobyte and mention catpaw to join the group.