Cluster Code

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';

// Register custom hooks
registerHooks([
  {
    name: 'before:agent:start',
    handler: async event => {
      console.log('Agent starting with:', event.context);
      return { success: true };
    },
    priority: 0,
  },
  {
    name: 'agent:tool:result',
    handler: async event => {
      console.log('Tool result:', event.toolName);
      return { success: true };
    },
  },
]);

Available Hooks

| Hook | Description | | ------------------------ | --------------------------- | | before:agent:start | Before agent session starts | | agent:tool:call | When a tool is called | | agent:tool:result | After tool execution | | before:command:execute | Before command execution | | after:command:execute | After command execution | | before:diagnostic:run | Before diagnostic run | | diagnostic:result | After diagnostic completion | | cluster:connect | When connecting to cluster | | llm:call | LLM API call events | | session:start | Session start | | session:end | Session end |

See Hooks Documentation for details.

🔌 Plugin Architecture

• cluster-core - Core Kubernetes operations
• k8sgpt-analyzers - AI-powered diagnostics
• cluster-openshift - OpenShift-specific features
• cloud-providers - Multi-cloud provisioning
• gitops - Deployment automation

Learn more about plugins →

🤝 Contributing

We welcome contributions! Check out our contributing guide to get started.

📝 License

MIT License - see LICENSE for details

🔗 Links

• Documentation
• GitHub Issues
• Changelog
• pi-mono - Inspiration for hooks system

Ready to get started? Install cluster-code and check out our Quick Start Guide →