swarmcode 0.1.1
Open-source AI coding assistant powered by Cerebras - fast inference for Llama 3.3 70B and Qwen3 Coder 480B
License: MIT
Requires Python: >=3.10
Keywords: ai, assistant, cerebras, code-generation, coding, development-tools, llama, qwen

# 🚀 SwarmCode 🚀

*The open-source AI coding assistant that actually works with Cerebras and other providers*

![Build Status](https://img.shields.io/badge/build-passing-brightgreen)
![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

*"Who needs expensive AI IDEs when you have SwarmCode?"* 

## Overview

SwarmCode is a powerful AI-powered code generation agent that works with **Cerebras**, OpenAI, Gemini, and other providers. Built as a response to expensive proprietary tools, SwarmCode gives you complete control over your AI coding assistant.

## ✨ Features

- **🧠 Cerebras Integration**: Fast inference with Cerebras models (Llama 3.3 70B, Qwen3 Coder 480B)
- **🌐 Multi-Provider Support**: Works with OpenAI, Gemini, Anthropic, Together AI, and custom endpoints
- **💻 Interactive CLI**: Beautiful command-line interface with rich formatting
- **📚 RAG Support**: Built-in embeddings and vector search for context-aware coding
- **🔧 MCP Server Support**: Extensible with Model Context Protocol servers
- **🚫 No Vendor Lock-in**: Use any model provider you want

## 🎬 Demo

![SwarmCode Demo](code_puppy.gif)

## 🚀 Quick Start

### Option 1: One-Line Install (Recommended) 🎯

```bash
curl -sSL https://raw.githubusercontent.com/rinadelph/swarmcode/main/install.sh | bash
```

That's it! The installer will:
- ✅ Check your Python version
- ✅ Install SwarmCode and all dependencies
- ✅ Prompt for your Cerebras API key
- ✅ Configure your preferred model
- ✅ Set up the `swm` command globally

### Option 2: Install from PyPI (Coming Soon)

```bash
pip install swarmcode
swm --interactive
```

### Option 3: Install from Source

```bash
# Clone and install
git clone https://github.com/rinadelph/swarmcode.git
cd swarmcode
python3 install.py

# Start coding!
swm --interactive
```

## 📋 Requirements

- **Python 3.10+**
- **API Keys** (at least one):
  - Cerebras API key (recommended) - [Get it here](https://cerebras.ai)
  - OpenAI API key
  - Gemini API key
  - Anthropic API key
  - Or any custom endpoint

## 🎯 Usage Examples

### Interactive Mode
```bash
# Start interactive session with Cerebras
swarmcode --interactive

# Or use a specific model
export MODEL_NAME=Cerebras-Qwen3-Coder-480b
swarmcode --interactive
```

### Direct Task Execution
```bash
# Execute a task directly
swarmcode "write a Python FastAPI server with user authentication"

# Generate and run code
swarmcode "create a React component for a todo list and set up the project"
```

### Using Different Providers

#### Cerebras (Recommended)
```bash
export CEREBRAS_API_KEY='your-key'
export MODEL_NAME='Cerebras-Llama-3.3-70b'
swarmcode --interactive
```

#### OpenAI
```bash
export OPENAI_API_KEY='your-key'
export MODEL_NAME='gpt-4.1'
swarmcode --interactive
```

#### Gemini
```bash
export GEMINI_API_KEY='your-key'
export MODEL_NAME='gemini-2.5-flash-preview-05-20'
swarmcode --interactive
```

#### Custom Endpoints
```bash
export MODEL_NAME='my-custom-model'
export MODELS_JSON_PATH='/path/to/custom/models.json'
swarmcode --interactive
```

## 🔧 Configuration

### Environment Variables
Create a `.env` file in your project root:

```bash
# Primary configuration
MODEL_NAME=Cerebras-Llama-3.3-70b
CEREBRAS_API_KEY=your_cerebras_api_key

# Optional providers
OPENAI_API_KEY=your_openai_key
GEMINI_API_KEY=your_gemini_key
ANTHROPIC_API_KEY=your_anthropic_key

# Behavior
YOLO_MODE=true  # Skip confirmation prompts for commands
```

### Available Cerebras Models
- `Cerebras-Llama-3.3-70b` - Fast, general purpose (default)
- `Cerebras-Qwen3-Coder-480b` - Specialized for coding
- `Cerebras-Qwen3-235b-a22b-instruct-2507` - Large instruction model
- `Cerebras-gpt-oss-120b` - Open source GPT variant

See `cerebras_models.json` for full list.

## 🛠️ Advanced Features

### RAG (Retrieval Augmented Generation)
SwarmCode includes built-in RAG support for better context awareness:

```bash
# Index your codebase
python index_code_puppy.py

# Use with embeddings
swarmcode --interactive --use-rag
```

### MCP Server Integration
Connect to external tools and services:

## Puppy Rules
Puppy rules allow you to define and enforce coding standards and styles that your code should comply with. These rules can cover various aspects such as formatting, naming conventions, and even design guidelines.

### Example of a Puppy Rule
For instance, if you want to ensure that your application follows a specific design guideline, like using a dark mode theme with teal accents, you can define a puppy rule like this:

```plaintext
# Puppy Rule: Dark Mode with Teal Accents

  - theme: dark
  - accent-color: teal
  - background-color: #121212
  - text-color: #e0e0e0

Ensure that all components follow these color schemes to promote consistency in design.
```

## Using MCP Servers for External Tools

Code Puppy supports **MCP (Model Context Protocol) servers** to give you access to external code tools and advanced features like code search, documentation lookups, and more—including Context7 (https://context7.com/) integration for deep docs and search!

### What is an MCP Server?
An MCP server is a standalone process (can be local or remote) that offers specialized functionality (plugins, doc search, code analysis, etc.). Code Puppy can connect to one or more MCP servers at startup, unlocking these extra commands inside your coding agent.

### Configuration
Create a config file at `~/.code_puppy/mcp_servers.json`. Here’s an example that connects to a local Context7 MCP server:

```json
{
  "mcp_servers": {
     "context7": { 
        "url": "https://mcp.context7.com/sse"
     }
  }
}
```

You can list multiple objects (one per server).

### How to Use
- Drop the config file in `~/.code_puppy/mcp_servers.json`.
- Start your MCP (like context7, or anything compatible).
- Run Code Puppy as usual. It’ll discover and use all configured MCP servers.

#### Example usage
```bash
code-puppy --interactive
# Then ask: Use context7 to look up FastAPI docs!
```

That’s it!
If you need to run more exotic setups or connect to remote MCPs, just update your `mcp_servers.json` accordingly.

**NOTE:** Want to add your own server or tool? Just follow the config pattern above—no code changes needed!

---

## Conclusion
By using Code Puppy, you can maintain code quality and adhere to design guidelines with ease.