gitops

Cluster Code

🎬 Demo

AI-powered CLI tool for Kubernetes and OpenShift cluster management with intelligent diagnostics, multi-cloud support, and GitOps workflows. Inspired by pi-mono.

⚡ Quick Start

Install

npm install -g cluster-code

Configure LLM Provider

# Option 1: Auto-detect from Claude Code (if ~/.claude/settings.json exists)
# cluster-code will automatically use your Claude API key

# Option 2: Set environment variables
export ANTHROPIC_API_KEY=your-api-key  # Anthropic (Claude)
export OPENAI_API_KEY=your-api-key     # Or OpenAI

# Option 3: Use local models (no API key needed)
ollama pull llama3
cluster-code config provider add ollama

Connect & Go

cluster-code init
cluster-code

That's it! Start chatting with your cluster in plain English.

✨ Key Features

• 💬 Natural Language Interface - Control your cluster using plain English
• 🤖 Agentic Mode - Autonomous execution with Claude Agent SDK
• 🔍 AI-Powered Diagnostics - Intelligent troubleshooting with K8sGPT
• ☁️ Multi-Cloud Support - AWS EKS, Azure AKS/ARO, GCP GKE
• 🚀 GitOps Ready - Helm, Kustomize, ArgoCD, Flux integration
• 🔒 Local LLM Support - Use Ollama for complete data privacy
• 🎯 OpenShift Native - Routes, Operators, BuildConfigs support
• 🤖 RL-Based Management - Optional PufferLib integration for training AI agents
• 🔐 GitHub Copilot Integration - OAuth authentication and multi-model support
• 🖥️ Multiple UI Modes - Interactive, TUI, and legacy chat modes
• 🪝 Extensible Hooks System - Plugin architecture inspired by pi-mono

📚 Documentation

View Full Documentation →

• Installation Guide - Detailed setup instructions
• LLM Provider Setup - Configure Anthropic, OpenAI, Google, or local models
• Getting Started - First steps and tutorials
• PufferLib RL Guide - Reinforcement learning for cluster management
• Hooks & Plugins - Extend cluster-code with custom hooks
• API Reference - Complete command reference

💡 Usage Examples

Interactive Mode (Default)

# Start interactive natural language interface
$ cluster-code
# or explicitly
$ cluster-code interactive

You: Show me all pods that are failing
You: Why is my deployment crashing?
You: Scale my app to 5 replicas

Agentic Mode (Autonomous Execution)

# Start agentic mode with Claude Agent SDK (Claude-only)
$ cluster-code agent
# or with a specific task
$ cluster-code agent "Fix all failing pods in the cluster"

TUI Mode

# Start terminal user interface
$ cluster-code ui

Direct Commands

# Run cluster diagnostics
cluster-code diagnose

# Show cluster and CLI info
cluster-code info

# Initialize cluster connection
cluster-code init

# Run first-time setup wizard
cluster-code setup

Model & Authentication Management

# Configure model interactively
cluster-code --configure-model

# List available models
cluster-code --list-models

# Use a specific model for this session
cluster-code --model gpt-4

# Set default model permanently
cluster-code --set-default-model claude-3-opus

# GitHub Copilot authentication
cluster-code --setup-github
cluster-code --show-auth
cluster-code --whoami
cluster-code --test-connection
cluster-code --logout-github

Reinforcement Learning (Optional)

Train AI agents to automatically manage your cluster using PufferLib:

# Set up RL environment (optional during init)
cluster-code rl setup

# Train an agent
cluster-code rl train --episodes 500

# Run RL-based diagnostics
cluster-code rl diagnose

See the PufferLib RL Guide for details.

🪝 Hooks System

Cluster-code features an extensible hooks system inspired by pi-mono:

import { hooks, registerHooks } from 'cluster-code';