English | 中文

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.

• 🪶 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
• 📡 Flexible notification — console, generic WebAPI, Flashduty, PagerDuty, or any combination
• 🔄 Self-monitoring friendly — ideal for monitoring your monitoring systems

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

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, Redis Sentinel, etc.) contribute their own specialized diagnostic tools for deep introspection.

For Redis-specific checks, cluster semantics, and diagnosis tools, see plugins/redis/README.md. For Redis Sentinel-specific checks, diagnosis tools, and config semantics, see plugins/redis_sentinel/README.md.

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

Download the binary from GitHub Releases.

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.

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"

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.

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

• Global config: conf.d/config.toml
• Local override: conf.d/config.local.toml (loaded last, git-ignored, ideal for developer-only changes)
• Plugin configs: conf.d/p.<plugin>/*.toml (multiple files merged on load)
• Top-level load order: config.toml -> other files in conf.d/ -> config.local.toml
• Hot-reload plugin configs with SIGHUP:

kill -HUP $(pidof catpaw)

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