xerxes 0.3.1
An intelligent agent with BYOK for managing cloud infrastructure & bash env
License: MIT
Requires Python: >=3.10
Keywords: agent, ai, aws, devops, docker, gcp, kubernetes, llm

# Xerxes

<div align="center">

**An intelligent DevOps agent with unrestricted CLI access and free-form reasoning**

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Documentation](#-usage) • [Contributing](#-contributing)

</div>

---

## Overview

Xerxes is an intelligent DevOps assistant that transforms natural language into bash commands. Unlike traditional tools with predefined commands, Xerxes leverages **full bash capabilities** with **intelligent resource discovery** to execute complex operations across your entire infrastructure.

## Features

### Core Capabilities

- **Full Bash Shell Access**: Execute ANY command with complete shell features
  - Pipes, redirection, chaining (`|`, `>`, `>>`, `&&`, `||`)
  - Variables, loops, conditionals, subshells
  - Process substitution and command expansion
- **Intelligent Resource Discovery**: Automatic fuzzy matching and pattern-based discovery
  - Never assumes exact names - always discovers first
  - Pattern: `SEARCH → MATCH → OPERATE`
  - Works with files, pods, containers, instances, and more
- **Token-Efficient Operations**: Minimal output formatting for faster responses
  - Uses `-o name`, `--format`, `--query` flags
  - Field projection to reduce token usage
- **Interactive Approval**: See command + reasoning before execution
  - `[R]un` - Execute this command
  - `[S]kip` - Skip and continue
  - `[A]lways` - Auto-approve for session
- **Multi-Cloud & Multi-Tool**: kubectl, docker, aws, gcloud, helm, jq, ffmpeg, git, and more
- **Safety First**: Automatic detection of destructive operations with confirmation prompts

## Installation

### Using UV (Recommended)

```bash
uv tool install xerxes
```

To update to the latest version:

```bash
uv tool upgrade xerxes
```

### From Source

```bash
git clone https://github.com/shammianand/xerxes.git
cd xerxes
uv sync
```

## Quick Start

### 1. Prerequisites

- **Python 3.10+**
- **GCP Project** with Vertex AI API enabled
- **Service Account** or API key for Vertex AI
- **Optional**: Install CLI tools you want to use (kubectl, docker, aws, gcloud)

### 2. Configuration

Create a `.env` file:

```bash
XERXES_VERTEX_PROJECT_ID=your-gcp-project-id
XERXES_VERTEX_LOCATION=us-central1
XERXES_VERTEX_MODEL=gemini-2.0-flash
XERXES_GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

Or use the CLI:

```bash
xerxes config set vertex_project_id your-gcp-project-id
xerxes config set google_application_credentials /path/to/sa.json
```

### 3. Start Chatting

```bash
xerxes chat
```

## Usage

### Example Session


https://github.com/user-attachments/assets/350d91eb-b999-4c18-aba3-52d4e430bb8e


**Operations:**
```
"Scale the api deployment to 5 replicas"
"Delete all pods in failed state"
"Create a new GCS bucket for backups"
```

## CLI Commands

```bash
# Start interactive chat
xerxes chat

# Manage configuration
xerxes config show
xerxes config set <key> <value>

# List available tools
xerxes tools

# Show version
xerxes version
```

## Configuration Options

| Variable | Description | Default |
|----------|-------------|---------|
| `XERXES_VERTEX_PROJECT_ID` | GCP project ID (required) | - |
| `XERXES_VERTEX_LOCATION` | GCP region | `us-central1` |
| `XERXES_VERTEX_MODEL` | Model name | `claude-3-5-sonnet@20240620` |
| `XERXES_GOOGLE_APPLICATION_CREDENTIALS` | Path to service account JSON | - |
| `XERXES_MAX_TOKENS` | Max tokens per response | `4096` |
| `XERXES_TEMPERATURE` | LLM temperature | `0.0` |

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests and linters:
   ```bash
   uv run pytest
   uv run black src/
   uv run ruff check src/
   ```
5. Commit your changes (`git commit -m 'Add amazing feature'`)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

## Development Setup

```bash
# Clone the repo
git clone https://github.com/shammianand/xerxes.git
cd xerxes

# Install dependencies
uv sync --all-extras

# Run in development mode
uv run xerxes chat
```

## Roadmap

- [ ] Additional LLM providers (Anthropic direct, OpenAI, Ollama)
- [ ] Terraform integration
- [ ] Ansible playbook execution
- [ ] Multi-step workflow automation
- [ ] Session history save/replay
- [ ] Web dashboard for monitoring
- [ ] Plugin system for custom tools
- [ ] One-shot command mode (`xerxes run "list all pods"`)

## License

MIT License - see [LICENSE](LICENSE) for details

## Support

- **Bug Reports**: [Open an issue](https://github.com/shammianand/xerxes/issues)
- **Feature Requests**: [Start a discussion](https://github.com/shammianand/xerxes/discussions)
- **Documentation**: Coming soon

---

<div align="center">

**Built with ❤️ by [Shammi Anand](https://github.com/shammianand)**

</div>