✅ Verified end-to-end on Windows with local Ollama (llama3.1, num_ctx=8192) — every command below is from a real run.

FlowSentry is an AI ops agent for n8n. Feed it your execution logs and it detects failure spikes, duration anomalies, and repeated error clusters — then a local LLM writes the root-cause analysis and a Slack-ready digest. Built by someone who has owned production n8n instances and got tired of finding out about broken workflows from clients.

How it works

flowchart LR
    A[n8n executions<br/>export / webhook] --> B[detectors<br/>failure spikes · z-score latency · error clusters]
    B --> C[LLM root-cause<br/>Ollama or Groq, free]
    C --> D[digest.md]
    D --> E[Slack webhook<br/>optional]

    style B stroke:#ffbd2e,stroke-width:2px
    style C stroke:#7ee787,stroke-width:2px

Loading

Three detectors, all explainable (no ML black box for paging decisions):

Detector	Fires when	Severity
failure_spike	≥30% of a workflow's runs fail (min 5 runs)	critical ≥50%
slow_workflow	recent runs >2.5σ above the workflow's mean duration	warning
error_cluster	the same error message appears ≥3×	warning

The LLM only explains findings — detection is deterministic, so you can trust the digest and audit every alert.

Quickstart

pip install -r requirements.txt
ollama pull llama3.1          # or set GROQ_API_KEY for Groq's free tier

# try it immediately on the bundled sample (120 executions, 3 seeded incidents)
python cli.py examples/sample_executions.json

# post the digest to Slack too
export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...
python cli.py executions.json --slack

Sample output:

Loaded 120 executions
critical  Client Onboarding: 17/30 runs failing (57%)
warning   Invoice Reminders: recent runs up to 6.8s vs 1.5s average
warning   Client Onboarding: same error 17x — "Airtable API error: INVALID_PERMISSIONS..."

Digest written → digest.md

Full digest from that exact run (LLM root-cause included): examples/sample_digest.md

Getting executions out of n8n

• Export: n8n UI → Executions → select → Download (JSON), or query the execution_entity table on self-hosted instances
• Continuous: point an n8n Error Trigger workflow at a tiny HTTP endpoint that appends to a JSON file, and run FlowSentry on a schedule (cron / Task Scheduler / another n8n workflow — dogfooding encouraged)

Configuration

Variable	Default	Purpose
OLLAMA_MODEL	llama3.1	Local model (default provider)
GROQ_API_KEY	—	Switch to Groq free tier
SLACK_WEBHOOK_URL	—	Enable --slack posting

Roadmap

• Direct Postgres reader for self-hosted n8n
• Baseline persistence (compare today vs. 7-day norm)
• MTTR tracking per workflow

---

Built by Ahmad Bukhari — AI & Automation Architect · agentic systems that run real businesses, not just demos