rootcause

Quick Install

```bash

Or install a specific skill

cp -r skills/claude/k8s-helm ~/.claude/skills/ ```

Getting Started

Installation

Homebrew:

brew install yindia/homebrew-yindia/rootcause

Curl install:

curl -fsSL https://raw.githubusercontent.com/yindia/rootcause/refs/heads/main/install.sh | sh

Go install:

go install .

Or build a local binary:

go build -o rootcause .

Supported OS: macOS, Linux, and Windows.

Windows build example:

go build -o rootcause.exe .

Docker

```bash

Build local image

docker build -t rootcause:local .

MCP Client Setup 🌐

All MCP clients use the same core values: - command: rootcause - args: usually --config /path/to/config.toml - env: optional KUBECONFIG

Validate setup (all providers)

1. Restart your client after editing MCP config.
2. Ask: "List RootCause tools".
3. Ask: "Run k8s.argocd_detect".
4. If tools are missing, verify rootcause path, --toolsets, and KUBECONFIG.

Install agent-browser

npm install -g agent-browser agent-browser install

Use Cases

Example: GitHub Copilot project files

rootcause sync-skills --agent copilot --project-dir .

Quick Start 🚀

1) Run the server:

go run . --config config.example.toml

2) Use your existing kubeconfig (default) or point to one:

• Uses KUBECONFIG if set, otherwise ~/.kube/config.
• Override with --kubeconfig and --context.

3) Connect your MCP client using stdio.

RootCause is built for local development. No API keys are required in this version.

Safe-by-default workflow: diagnose read-only first, then run mutation preflight before any write operation.

---

Usage

Initialize a home config with every built-in toolset enabled and custom skills configured:

rootcause init-config

This writes ${HOME}/.rootcause/config.toml on macOS/Linux and %USERPROFILE%\.rootcause\config.toml on Windows, creates the sibling skills/ directory, and refuses to overwrite unless --overwrite is passed.

Run with a config file:

rootcause --config config.toml

Enable a subset of toolchains:

rootcause --toolsets k8s,istio

Enable read-only mode:

rootcause --read-only

Sync skills into agent-specific project directories:

rootcause sync-skills --agent claude --project-dir .

---

MCP Client Example (stdio)

rootcause --config config.toml

Point your MCP client to run the command above and use stdio transport.

---

Example Operator Flows 🧪

Contributing Guide 🤝

We welcome code, docs, tests, and operational feedback.

Optional: Browser Automation (26 Tools)

Automate web-based Kubernetes operations with agent-browser integration.

Quick setup:

```bash

Browser (`browser_*`, optional)

• browser_open, browser_screenshot, browser_click, browser_fill, browser_test_ingress, browser_screenshot_grafana, browser_health_check
• browser_snapshot, browser_get_text, browser_get_html, browser_evaluate, browser_pdf, browser_wait_for, browser_wait_for_url
• browser_press, browser_select, browser_check, browser_uncheck, browser_hover, browser_type, browser_upload, browser_drag
• browser_new_tab, browser_switch_tab, browser_close_tab, browser_close

Config and Flags

rootcause --config config.example.toml --toolsets k8s,linkerd,istio,karpenter,helm,aws

Create a cross-platform home config first if you do not already have one:

rootcause init-config

The generated config enables k8s, linkerd, karpenter, istio, helm, aws, terraform, and rootcause, sets stdio transport defaults, and configures ~/.rootcause/skills as the custom skill folder.

Kubeconfig Resolution

If --kubeconfig is not set, RootCause follows standard Kubernetes loading rules: it uses KUBECONFIG when present, otherwise defaults to ~/.kube/config.

Authentication and authorization use your kubeconfig identity only in this version.

---

kubeconfig not found

• Verify KUBECONFIG or ~/.kube/config
• Override explicitly with --kubeconfig /path/to/config

Config Reload

Send SIGHUP to reload config and rebuild the tool registry. On Windows, SIGHUP is not supported; restart the process to reload config.

---

Development references

• Contribution rules: CONTRIBUTING.md
• Plugin SDK and external toolsets: PLUGINS.md
• Config example: config.toml
• MCP eval harness: eval/README.md

Contributor workflow

1. Fork and create a feature branch
2. Implement focused changes with tests
3. Run local verification:

go test ./...

1. Update docs (README.md, prompts/prompt.md) if behavior changed
2. Open PR with problem statement, approach, and verification notes

GitHub Copilot (VS Code)

File: VS Code settings.json (MCP-enabled builds)

{
  "mcp.servers": {
    "rootcause": {
      "command": "rootcause",
      "args": ["--config", "/Users/you/.config/rootcause/config.toml"],
      "env": { "KUBECONFIG": "/Users/you/.kube/config" }
    }
  }
}

Troubleshooting