Rootcause

RootCause 🧭

[](https://go.dev/) [](https://modelcontextprotocol.io/) [](https://codecov.io/gh/yindia/rootcause)

AI-native SRE for Kubernetes incidents.

RootCause is a local-first MCP server that turns natural-language requests into evidence-backed incident analysis, Kubernetes diagnostics, and safer operations.

Built in Go as a single binary, RootCause is optimized for low-friction local workflows using your existing kubeconfig identity.

---

[🚀 Quick Start](#quick-start-) | [🌐 Client Setup](#mcp-client-setup-) | [🛠️ Tools](#tools) | [🧩 Skills](#agent-skills) | [🔒 Safety](#safety-modes) | [⚙️ Config](#config-and-flags) | [🏗️ Architecture](#architecture-overview) | [🤝 Contributing](#contributing-guide-)

---

Why RootCause 💡

RootCause is built for SRE/operator workflows where speed matters, but unsafe automation is unacceptable.

• 🚀 Stop context-switching: investigate incidents, rollout risk, Helm/Terraform/AWS signals, and remediation from one MCP server.
• 🧠 AI-powered diagnostics: evidence-first analysis with RCA, timelines, and action-oriented next checks.
• 💸 Built-in cost optimization: combine resource usage, workload best-practice checks, Terraform plan analysis, and cloud context for optimization decisions.
• 🔒 Enterprise-ready guardrails: role/namespace policy enforcement, redaction, read-only mode, destructive tool controls, and mutation preflight.
• ⚡ Zero learning curve: ask natural-language operational questions and use provided prompt templates for common SRE flows.
• 🌐 Universal compatibility: works with MCP-compatible clients across Claude, Cursor, Copilot, Codex, and more.
• 🏭 Production-grade workflow: single Go binary, kubeconfig-native auth, deterministic structured outputs, and broad test coverage.

Why teams choose it

| Need | RootCause answer | |---|---| | "What changed and why did this break?" | rootcause.incident_bundle, rootcause.change_timeline, rootcause.rca_generate | | "Is it safe to restart or roll out now?" | k8s.restart_safety_check, k8s.best_practice, k8s.safe_mutation_preflight | | "Is my platform ecosystem healthy?" | k8s.*_detect + k8s.diagnose_* for ArgoCD/Flux/cert-manager/Kyverno/Gatekeeper/Cilium | | "Can I standardize SRE responses?" | Prompt templates + structured output from shared render/evidence pipeline |

What Can You Do?

Ask your AI assistant in natural language:

• "Why did this deployment fail after rollout?"
• "Is this workload safe to restart right now?"
• "Why are ArgoCD apps out of sync?"
• "Is Flux healthy in this cluster?"
• "Why are certs failing to renew?"
• "Before patch/apply, is this mutation safe?"

RootCause keeps its depth-first model: evidence-first diagnosis, root-cause analysis, and remediation flow instead of raw tool sprawl.

Power users can map these prompts to concrete tools in this README (Complete Feature Set, Toolchains, and Tools sections).

Use Cases

Incident response

• Build end-to-end incident evidence with rootcause.incident_bundle
• Generate probable causes with rootcause.rca_generate
• Export timeline and postmortem artifacts for follow-up

Safe operations before mutation

• Evaluate rollout/restart risk with k8s.restart_safety_check and k8s.best_practice
• Run k8s.safe_mutation_preflight before apply/patch/delete/scale operations

Ecosystem-specific health checks

• ArgoCD: detect installation and diagnose sync/health drift
• Flux: detect controllers and diagnose reconciliation failures
• cert-manager / Kyverno / Gatekeeper / Cilium: detect footprint and diagnose control-plane or policy issues

Feature Highlights

| Area | RootCause Capability | |---|---| | Incident analysis | rootcause.incident_bundle, rootcause.rca_generate, rootcause.change_timeline, rootcause.postmortem_export, rootcause.capabilities | | Kubernetes resilience | k8s.restart_safety_check, k8s.best_practice, k8s.safe_mutation_preflight | | Ecosystem diagnostics | ArgoCD/Flux/cert-manager/Kyverno/Gatekeeper/Cilium via *_detect and diagnose_* tools | | Deployment safety | Automatic preflight before k8s mutating operations | | Helm operations | Chart search/list/get, release diff, rollback advisor, template apply/uninstall flows | | Terraform analysis | Module/provider search + terraform.debug_plan for impact/risk analysis | | Service mesh & scaling | Linkerd/Istio/Karpenter diagnostics with shared evidence model |

Complete Feature Set

| Category | Representative capabilities | |---|---| | Kubernetes core (k8s.*) | CRUD, logs/events, graph-based debug flows, restart safety, best-practice scoring, mutation preflight | | Ecosystem diagnostics | ArgoCD, Flux, cert-manager, Kyverno, Gatekeeper, Cilium via *_detect and diagnose_* | | Incident intelligence (rootcause.*) | Incident bundle orchestration, timeline export, RCA generation, remediation playbook, postmortem export | | Helm operations (helm.*) | Chart registry search/list/get, release status/diff, rollback advisor, install/upgrade/uninstall, template apply/uninstall | | Terraform analysis (terraform.*) | Modules/providers/resources/data source discovery + plan debugging | | Service mesh (istio.*, linkerd.*) | Proxy/config/status diagnostics, policy/routing visibility, mesh resource health | | Cluster autoscaling (karpenter.*) | Provisioning, nodepool/nodeclass, interruption and scheduling diagnostics | | Cloud context (aws.*, gcp.*) | AWS: IAM, VPC, EC2, EKS, ECR, STS, KMS diagnostics. GCP: Cloud Monitoring metrics + SLOs, Cloud Logging entries, workload-scoped error timelines for cross-layer incident analysis | | Safety and controls | Read-only mode, destructive gating, explicit confirmation, auto preflight checks before mutating K8s operations |

Agent Skills

Extend your AI coding agent with Kubernetes and RootCause expertise using the built-in skills library in skills/.

Skills metadata is schema-versioned and embedded in the CLI from internal/skills/catalog/manifest.json.

Quick Install

# Copy all skills to Claude
cp -r skills/claude/* ~/.claude/skills/

# Or install a specific skill
cp -r skills/claude/k8s-helm ~/.claude/skills/

Sync prompts and skills into your agent

One command syncs both prompts (as slash commands) and skills (as agent-side guidance) into your AI client's native directories. By default everything is synced; use --prompts-only or --skills-only for granular control. Custom prompts under ~/.rootcause/prompts/ and custom skills under ~/.rootcause/skills/ are picked up automatically.

# List supported agents (shows both commands + skills directories)
rootcause sync --list-agents

# List everything available (built-in + custom prompts and skills)
rootcause sync --list

# Default: sync both prompts and skills for one agent (project-local)
rootcause sync --agent claude --project-dir .

# User-globally — writes ~/.claude/commands/ and ~/.claude/skills/
rootcause sync --agent claude --user

# All supported agents
rootcause sync --all-agents

# Granular control
rootcause sync --agent claude --prompts-only
rootcause sync --agent claude --skills-only
rootcause sync --agent claude --prompt observability_workload_diagnose
rootcause sync --agent claude --skill k8s-incident

# Existing files are NOT overwritten by default. Opt in:
rootcause sync --agent claude --overwrite

# Dry-run to see what would be written
rootcause sync --agent claude --dry-run

# Ignore custom directories and sync only built-ins
rootcause sync --agent claude --builtin-only

Prompts that took {{namespace}} / {{workload}} tokens become positional $1 / $2 in the generated slash command. Optional {{name|default}} tokens render with a "Defaults" preamble so the agent applies fallbacks when an argument is omitted.

Per-agent target directories:

| Agent | Slash commands | Skills | |---|---|---| | claude | .claude/commands/ | .claude/skills/ | | cursor | .cursor/commands/ | .cursor/skills/ | | codex | .codex/commands/ | .codex/skills/ | | copilot| .github/prompts/ | .github/skills/ | | gemini | .gemini/commands/ | .gemini/skills/ | | opencode| .opencode/commands/ | .opencode/skills/ | | windsurf| .windsurf/commands/ | .windsurf/skills/ | | aider | .aider/commands/ | .aider/skills/ | | devin, cody, amazonq | (no slash-command directory yet) | .devin/skills/ etc. |

User Custom Skills

Users can add team or personal skills in a folder containing one subdirectory per skill:

~/.rootcause/skills/
  team-runbook/
    SKILL.md

Use YAML front matter to standardize metadata and tags. Tags decide which MCP tool calls receive the skill as guidance:

---
category: Root Cause Analysis
description: Team-specific RCA checklist
tags: [rootcause, rca, payments]
---
# Team RCA

Always check the payments dashboard before declaring database root cause.

RootCause matches tags on every tool call using the toolset (rootcause, k8s, helm), exact tool name (rootcause.rca_generate), tool-name tokens (rca, events, timeline), plus optional call arguments skillTags or customSkillTags.

For all RootCause incident and issue analysis, tag the skill with rootcause. That applies it to every rootcause.* tool, including rootcause.incident_bundle, rootcause.rca_generate, rootcause.remediation_playbook, rootcause.postmortem_export, and rootcause.change_timeline.

Use narrower tags when the guidance should only apply to part of the flow:

| Goal | Recommended tags | |---|---| | All RootCause issue workflows | [rootcause] | | RCA drafting only | [rca] or [rootcause.rca_generate] | | Kubernetes issue analysis plus RootCause workflows | [rootcause, k8s, incident] | | A team/service-specific workflow | [rootcause, payments] plus pass skillTags: ["payments"] when needed |

Sync custom skills into supported agent directories:

rootcause sync --agent opencode --skills-only
rootcause sync --agent claude --custom-skill-dir ~/.rootcause/skills --skill team-runbook

Expose custom skills through MCP resources by initializing the home config:

rootcause init-config

or adding them to config manually:

skills:
  custom_dirs:
    - "~/.rootcause/skills"
    - "./skills/custom"
  allow_custom_overrides: false

MCP clients can read skill://catalog for the merged skill list and skill://team-runbook for the skill content. Custom names cannot collide with built-ins unless overrides are explicitly enabled.

Every tool call includes matching tagged custom skills in response metadata/payload as customSkillGuidance, so MCP agents can consider team-specific runbook instructions during root-cause analysis and other workflows.

Syncing skills into .claude/, .codex/, .opencode/, or other agent-specific directories is optional. Claude, Codex, OpenCode, and any MCP-compatible client can use configured custom skills through RootCause tool responses and skill://... resources without local skill sync. Syncing is only needed when you want the agent's native skill system to discover RootCause skills outside MCP tool calls.

Do not put secrets, credentials, kubeconfigs, tokens, or private incident data in custom SKILL.md files. Matching skills can be returned in MCP tool responses for the connected client to read.

Skill file formats per agent:

| Agent | Format | |---|---| | Claude Code, Codex, Gemini CLI, OpenCode, Aider, Sourcegraph Cody, Amazon Q | SKILL.md | | Cursor | .mdc | | GitHub Copilot, Windsurf, Devin | plain .md |

For the matching slash-command directories per agent, see the unified table earlier in this section.

Available Skills (22)

22 skills are currently included.

| Category | Skills | |---|---| | Incident Response | k8s-incident, rootcause-rca | | Core and Operations | k8s-core, k8s-operations | | Diagnostics and Debugging | k8s-diagnostics, k8s-troubleshoot | | Deployment and Delivery | k8s-deploy, k8s-helm, k8s-rollouts | | GitOps | k8s-gitops | | Networking and Mesh | k8s-networking, k8s-service-mesh, k8s-cilium | | Security and Policy | k8s-security, k8s-policy, k8s-gatekeeper, k8s-certs | | Cost and Scaling | k8s-cost, k8s-autoscaling | | Storage | k8s-storage | | Browser Automation | k8s-browser | | Cloud Observability | k8s-gcp |

Supported agents include Claude, Cursor, Codex, Gemini CLI, GitHub Copilot, Goose, Windsurf, Roo, Amp, and more.

Skills include consistent triggers, workflow steps, tool references, troubleshooting notes, and output contracts.

See skills/README.md for full documentation and skills/CATALOG.md for auto-generated catalog output.

MCP Resources

Access Kubernetes data as browsable resources:

| Resource URI | Description | |---|---| | kubeconfig://contexts | List all available kubeconfig contexts | | kubeconfig://current-context | Get current active context | | namespace://current | Get current namespace | | namespace://list | List all namespaces | | cluster://info | Get cluster connection info | | cluster://nodes | Get detailed node information | | cluster://version | Get Kubernetes version | | cluster://api-resources | List available API resources | | manifest://deployments/{namespace}/{name} | Get deployment YAML | | manifest://services/{namespace}/{name} | Get service YAML | | manifest://pods/{namespace}/{name} | Get pod YAML | | manifest://configmaps/{namespace}/{name} | Get ConfigMap YAML | | manifest://secrets/{namespace}/{name} | Get secret YAML (data masked) | | manifest://ingresses/{namespace}/{name} | Get ingress YAML |

MCP Prompts

Pre-built workflow prompts for Kubernetes and platform operations:

| Prompt | Description | |---|---| | troubleshoot_workload | Comprehensive troubleshooting guide for pods/deployments | | deploy_application | Step-by-step deployment workflow | | security_audit | Security scanning and RBAC analysis workflow | | cost_optimization | Resource optimization and cost analysis workflow | | disaster_recovery | Backup and recovery planning workflow | | debug_networking | Network debugging for services and connectivity | | scale_application | Scaling guide with HPA/VPA best practices | | upgrade_cluster | Kubernetes cluster upgrade planning | | sre_incident_commander | Severity-based SRE incident coordination workflow | | istio_mesh_diagnose | Diagnose Istio control-plane and traffic policy issues | | linkerd_mesh_diagnose | Diagnose Linkerd control-plane, proxy, and policy health | | helm_release_recovery | Recover failed Helm install/upgrade with rollback strategy | | terraform_drift_triage | Investigate Terraform drift and plan safety | | aws_eks_operational_check | EKS health, nodegroup, and IAM integration diagnostics | | karpenter_capacity_debug | Debug Karpenter provisioning and scheduling issues | | observability_workload_diagnose | Triage a workload via the configured observability backend (works for any cluster) |

Authoring custom prompts and skills

For a full walkthrough with a realistic example (AWS PrivateLink debugging), see [docs/AUTHORING.md](docs/AUTHORING.md). It covers writing a prompt, writing a complementary skill, syncing both into your client, and what happens when the AI runs the resulting workflow end-to-end.

Quick reference below.

Adding Custom Prompts (recommended: one file per prompt)

Drop one markdown file per prompt into ~/.rootcause/prompts/. Each file declares the prompt's metadata in YAML front-matter and the rendered text below.

~/.rootcause/prompts/
  team-status.md
  payments-p1-drill.md
  verify-deploy.md

Example — ~/.rootcause/prompts/team-status.md:

---
name: team_status
description: Daily status check for a workload
arguments:
  - name: workload
    description: Deployment name
    required:

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [yindia](https://github.com/yindia)
- **Source:** [yindia/rootcause](https://github.com/yindia/rootcause)
- **License:** MIT
- **Homepage:** https://deepwiki.com/yindia/rootcause

Install and usage instructions live in the source repository linked above.