chmonitor is an open-source operational advisor for ClickHouse, providing real-time monitoring and AI-driven recommendations for performance optimization. It targets engineers and power users managing ClickHouse clusters, offering actionable insights without auto-applying changes. Available as a self-hostable GPL-3.0 application or a managed cloud service.

How It Works

The system analyzes ClickHouse system.* tables and EXPLAIN plans to generate AI-powered recommendations for projections, skip indexes, partition keys, PREWHERE rewrites, and materialized views, strictly adhering to a "recommend-only" policy. It features real-time query/cluster monitoring, an AI Agent for natural-language querying, and an MCP Server for integrating with external AI tools. Built on Vite, React 19, and TanStack Start, it deploys as a native Workers bundle.

Quick Start & Requirements

Start quickly via Docker:

docker run -d --name chmonitor -p 3000:3000 \
  -e CLICKHOUSE_HOST=https://clickhouse.example.com:8443 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD=change-me \
  ghcr.io/chmonitor/chmonitor:latest

Access at http://localhost:3000. For Cloudflare Workers, Node.js 18+ and pnpm are needed. Production deployments should pin release tags. Docs: docs.chmonitor.dev, Demo: dash.chmonitor.dev.

Highlighted Details

• AI Optimization: Recommends projections, skip indexes, partition keys, PREWHERE clauses, and materialized views.
• AI Agent & MCP Server: Enables natural-language querying and integrates with AI tools (Claude, Cursor).
• Comprehensive Monitoring: Tracks query performance, cluster resources, replication, merges, and security.
• Flexible Deployment: Supports Docker, Kubernetes, bare metal, Cloudflare Workers, and one-click platforms.
• Rust CLI: Offers TUI monitoring and cluster health diagnostics (chm diagnose).

Maintenance & Community

Actively developed, with recent stack migration to TanStack Start/React 19 (v0.3). Feedback via issues/PRs is welcomed. Community channels (Discord/Slack) are not specified.

Licensing & Compatibility

Self-hosted is GPL-3.0 (copyleft), potentially restricting proprietary integration. Cloud has tiered subscriptions.

Limitations & Caveats

v0.3 is a significant stack upgrade. AI recommendations require human expert review before DDL application. Specific unsupported platforms or known bugs are not detailed.