Monix

English | 한국어

Overview

Monix is a terminal-native AI assistant for server monitoring. It pairs a slash-command CLI with a provider-backed conversational agent so operators can inspect CPU, memory, disk, processes, services, logs (plain files, Nginx, Docker), and webhook alerts without leaving the shell.

• Two interfaces, one mental model — fast /slash commands for known intents, natural-language chat for everything else. Both share the same underlying tools.
• Natural language configuration — ask Monix to register logs, configure webhooks, and toggle alerts; it calls the right tool and confirms what it did.
• Server-safe — never executes destructive server commands (rm, kill, systemctl restart, etc.). Only reads system state and writes to Monix's own config files under ~/.monix/.
• Zero runtime dependencies — standard library only (urllib, json, inspect, subprocess, …).
• Cross-platform — Linux (procfs) and macOS (vm_stat / sysctl).

Installation

macOS

pip install monix

Ubuntu / Debian

sudo apt install pipx && pipx install monix && pipx ensurepath && source ~/.bashrc

With MCP server support

pip install "monix[mcp]"
# or
pipx install "monix[mcp]"

Setup

1. Prepare a provider

• Gemini: get an API key at Google AI Studio.
• OpenAI Codex: use Monix's browser-based ChatGPT/Codex login; Codex CLI is not required.
• Anthropic: use Claude Pro/Max browser login or an Anthropic API key.

2. Run monix

monix

Run monix model to choose Gemini API Key, OpenAI login/API Key, or Anthropic login/API Key. OAuth credentials are stored as Monix-only sessions without requiring Codex CLI or Claude Code.

3. One-shot mode

monix /stat cpu
monix /log /var/log/syslog 100
monix "why is memory so high?"

MCP server

monix-mcp

Configuration

Change API key

monix --setup

Change platform (if auto-detection is wrong)

monix --set-platform

Environment variables

A .env file in the current directory is loaded automatically.

Webhook alerts (in-app)

/notify set discord https://discord.com/api/webhooks/...
/notify set slack https://hooks.slack.com/services/...
/notify status

Log error alerts

Monix can send a webhook notification when an error pattern is detected while streaming logs with --live. Triggered by ERROR, FATAL, CRITICAL, Exception, Traceback and similar patterns.

# Enable log error alerts
/notify set log-errors on

# Minimum severity: only ERROR (default) or also WARN
/notify set log-severity error

# Cooldown between repeated alerts for the same source (seconds)
/notify set log-cooldown 300

# Ignore lines containing a specific pattern (case-insensitive)
/notify set log-ignore add ConnectionRefused
/notify set log-ignore add "404 Not Found"
/notify set log-ignore list
/notify set log-ignore remove ConnectionRefused
/notify set log-ignore clear

Once enabled, any --live stream (/log @alias --live, /docker @alias --live) will automatically send webhook alerts for matching error lines while skipping ignored patterns.

Examples

> /stat cpu
  CPU 23.4%   load 0.41 / 0.38 / 0.30

> /log @api --search timeout
  [3 matches in last 500 lines]
  2026-04-26 12:14:02  ERROR  upstream timeout (10s) on /v1/orders
  ...

> show me containers using the most memory
  → tool: list_containers
  → tool: ... (correlates with snapshot)
  Top container by RSS is `payments-api` (1.2 GB / 2 GB cap).
  Recent restarts: 0.  Suggested follow-up: /docker logs payments-api

Natural Language Interface

All free-text input is routed to the configured LLM provider. The model selects from monitoring tools (read-only server inspection) and configuration tools (write to Monix's own config). Both produce the same Rich panel output as the equivalent slash command.

Monitoring queries

> why is CPU so high?
> show disk I/O
> check the nginx service
> tail the @api log
> find errors in the payments container

Configuration via natural language

Instead of memorising slash-command syntax, you can describe what you want:

> register /var/log/api.log as @api
  [Registered] app log: @api -> /var/log/api.log

> set Discord webhook to https://discord.com/api/webhooks/...
  Discord webhook URL saved.

> enable log error alerts with warn severity
  Log error alerts enabled.
  Minimum log alert severity set to 'warn'.

> ignore healthcheck lines in log alerts
  Ignore pattern added: 'healthcheck'

> set metrics collection every 1 hour, keep 30 days, store in ~/metrics
  Metrics collector configured
    Interval: 1.0h  /  Retention: 30.0d  /  Folder: ~/metrics

Safety boundary

Slash Commands

Snapshots and live monitoring

Logs

Docker

Notifications

Services and AI

Background metrics collector

Webhook alert configuration

Monix can format threshold alerts for Discord and Slack webhooks. Repeated identical alerts are rate-limited with a local state file at ~/.monix/notify_state.json.

export MONIX_DISCORD_WEBHOOK="https://discord.com/api/webhooks/..."
export MONIX_SLACK_WEBHOOK="https://hooks.slack.com/services/..."
export MONIX_NOTIFY_COOLDOWN=3600

# Per-metric notification toggles. Use 0, false, or no to disable.
export MONIX_NOTIFY_CPU=1
export MONIX_NOTIFY_MEM=1
export MONIX_NOTIFY_DISK=1

# Log error alert settings (--live mode)
export MONIX_NOTIFY_LOG_ERRORS=1       # Enable (default: 0=off)
export MONIX_NOTIFY_LOG_SEVERITY=error # error | warn
export MONIX_NOTIFY_LOG_COOLDOWN=300   # Cooldown between alerts per source (seconds)

Agent Conversation (Multi-Turn Internals)

Monix's conversational mode is a two-dimensional multi-turn loop, implemented in monix/core/assistant.py and monix/llm/.

Text responses are streamed incrementally via SSE (stream_round / chat_stream on GeminiClient), so output appears token-by-token while tool-specific Rich panels are preserved. Tool calls themselves are still executed synchronously within each round.

Tool categories

When a single read tool is called, its result is rendered directly as a Rich panel (same as the equivalent slash command). Config write tools return a confirmation message. Destructive actions (/log remove, /notify reset, etc.) are never executed by the model — it explains the CLI command instead.

Per-prompt loop

1. Take a fresh snapshot (CPU/mem/disk/processes/alerts) and
   append it, plus the registered log alias table, to the user
   text — gives the model a current "world view" up front.

2. Send working history + tool schemas → selected provider
   via streaming (stream_round).

3. Consume the SSE stream:
     • text chunks        → printed incrementally to the terminal.
     • functionCall(s)    → execute each via call_tool(),
                            append the model candidate (verbatim,
                            preserving thought_signature) and the
                            functionResponse parts to the working
                            history, then loop.
     • text only (no fc)  → terminal state, append (user, model)
                            to caller history and return.

4. After 5 rounds the loop exits with a tools-disabled streaming
   summary call (chat_stream) so the model is forced to answer
   with what it already saw.