Metadata-Version: 2.1
Name: xerocodeai
Version: 0.3.0
Summary: AI coding assistant — REPL + agent loop powered by OpenAI-compatible models
Author: Navadeep
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE

# xerocodeai

An autonomous AI coding assistant with an interactive REPL, agent loop, skills, and session persistence — powered by OpenAI-compatible models.

---

## ✨ Features

- **Interactive TUI** — arrow-key navigation, inline editing, clean interface
- **Smart Model Routing** — automatically selects the right model for the task (main, planner, summarizer)
- **Session Persistence** — resume your conversations across restarts
- **Single/Multi-Model Support** — use one model for everything or different models for different tasks
- **Provider Presets** — quick config for OpenAI, Anthropic, Groq, FreeModel, OpenRouter
- **Skills System** — extend with custom skills (`/init`, `/review`, `/test`, and more)
- **Memory Layers** — project-specific and global memory with AGENTS.md files
- **Permission Profiles** — control agent autonomy (confirm, yolo, danger modes)
- **File Snapshots** — automatic backups before file modifications

---

## 📦 Installation

```bash
pip install xerocodeai
```

**Requirements:** Python 3.9+

---

## 🚀 Quick Start

### 1. Get an API Key

You need an OpenAI-compatible API key. Get a free one at [freemodel.dev](https://freemodel.dev/invite/FRE-63e7c8c2) — no credit card required.

### 2. Configure xerocodeai

Run the command:

```bash
xerocodeai
```

Then inside the REPL, type:

```
/config
```

This opens the interactive config editor. Use:

- **↑ / ↓** — navigate between fields
- **Enter** — edit the selected field
- **a** — sync all models to the same value (single-model mode)
- **p** — apply a provider preset (OpenAI, Anthropic, Groq, etc.)
- **s** — save & exit
- **q / ESC** — quit without saving

### 3. Enter your API key

Navigate to "API key" and paste your key. It will be masked for security.

### 4. Start coding!

Type your request and press Enter. For example:

```
Create a Python script that fetches weather data from an API and displays it nicely.
```

---

## 🎯 Using `/config`

The config editor is the main setup tool. Here's what each setting does:

| Setting | Description | Example Value |
|---------|-------------|---------------|
| **Main model** | The primary model for agent reasoning | `gpt-4o`, `claude-sonnet-4-20250514` |
| **Planner model** | Model for planning and critique | `gpt-4o-mini`, `claude-3-5-haiku-20241022` |
| **Summarizer model** | Model for compressing conversation history | `gpt-4o-mini` |
| **Base URL** | API endpoint URL | `https://api.openai.com/v1` |
| **API key** | Your API authentication key | `sk-...` |

### Single-Model Mode

If your provider only gives you one model (e.g., you're on a limited plan), press **`a`** in the config editor to set all three models to the same value. This is perfectly fine and recommended for single-model providers.

### Provider Presets

Press **`p`** in the config editor to quickly configure for popular providers:

| Provider | Base URL | Main Model | Planner/Summarizer |
|----------|----------|-----------|-------------------|
| OpenAI | `https://api.openai.com/v1` | `gpt-4o` | `gpt-4o-mini` |
| Anthropic | `https://api.anthropic.com/v1` | `claude-sonnet-4` | `claude-3-5-haiku` |
| Groq | `https://api.groq.com/openai/v1` | `llama-3.1-70b` | `llama-3.1-8b` |
| FreeModel | `https://api.freemodel.dev/v1` | `gpt-5.5` | `gpt-5.4-mini` |
| OpenRouter | `https://openrouter.ai/api/v1` | `openai/gpt-4o` | `anthropic/claude-3-haiku` |

### Environment Variables (Alternative)

You can also set configuration via environment variables instead of using `/config`:

```bash
export XEROCODEAI_MAIN_MODEL="gpt-4o"
export XEROCODEAI_PLANNER_MODEL="gpt-4o-mini"
export XEROCODEAI_SUMMARIZER_MODEL="gpt-4o-mini"
export XEROCODEAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_API_KEY="sk-..."
```

---

## 📖 REPL Commands

| Command | Description |
|---------|-------------|
| `/config` | Open interactive config editor |
| `/help` | Show all commands and skills |
| `/diag` | Check model connectivity and API key |
| `/plan` | Toggle plan mode (enables planning before execution) |
| `/skills` | List available skills |
| `/todos` | Show current TODOs from the agent |
| `/tokens` | Show token usage statistics |
| `/memory` | Manage memory layers (view/edit AGENTS.md files) |
| `/profile` | Manage permission profiles (confirm, yolo, danger) |
| `/resume` | Resume a previous session |
| `/log` | View debug log |
| `/clear` | Reset current session |
| `exit` or Ctrl+D | Quit xerocodeai |

### Skills

Skills are slash commands that inject special instructions:

- `/init` — Initialize a new project with AGENTS.md
- `/review` — Review code and provide feedback
- `/test` — Write tests for your code

---

## 🔧 Configuration Storage

xerocodeai stores configuration in your home directory, **not** in your project:

```
~/.xerocodeai/
├── config.json          # API key, models, base_url
├── debug.log           # Debug logs (rotated)
├── history             # Command history (persistent)
├── sessions/           # Conversation history by project
│   └── <project-hash>/
├── snapshots/          # File backups before modifications
├── MEMORY.md           # Global memory (follows you across projects)
└── settings.json       # Skills settings
```

### Session Persistence

Your conversations are automatically saved and can be resumed with `/resume`. Session data is stored in `~/.xerocodeai/sessions/` and scoped by project (different projects don't interfere).

---

## 🔐 Security & Permissions

### Permission Profiles

xerocodeai has three profiles that control autonomy:

| Profile | Behavior |
|---------|----------|
| **confirm** (default) | Asks before any file write or shell command |
| **yolo** | Auto-approves read operations and safe actions |
| **danger** | Auto-approves everything (use with caution) |

Switch profile with:

```
/profile set yolo
```

Set environment variable to start with a specific profile:

```bash
export XEROCODEAI_PROFILE="yolo"
```

Or force yes for all prompts:

```bash
export XEROCODEAI_ASSUME_YES="1"
```

### Auto-Resume

On startup, xerocodeai offers to resume the most recent session if it's less than 24 hours old and contains at least 2 messages. Disable with:

```bash
export XEROCODEAI_NO_RESUME="1"
```

---

## 🛠️ Environment Variables

All configuration keys have corresponding environment variables:

| Setting | Env Var |
|---------|---------|
| `model` | `XEROCODEAI_MAIN_MODEL` |
| `planner_model` | `XEROCODEAI_PLANNER_MODEL` |
| `summarizer_model` | `XEROCODEAI_SUMMARIZER_MODEL` |
| `base_url` | `XEROCODEAI_BASE_URL` |
| `api_key` | `OPENAI_API_KEY` |
| `profile` | `XEROCODEAI_PROFILE` |
| `home` | `XEROCODEAI_HOME` (overrides `~/.xerocodeai`) |
| `no_resume` | `XEROCODEAI_NO_RESUME` |
| `assume_yes` | `XEROCODEAI_ASSUME_YES` |
| `auto_route` | `XEROCODEAI_AUTO_ROUTE` (enable smart model routing) |
| `log_level` | `XEROCODEAI_LOG_LEVEL` (DEBUG, INFO, WARNING, ERROR) |

---

## 💡 Examples

### Example 1: Simple coding task

```
Create a Python function that validates email addresses using regex.
```

The agent will:
1. Plan (if in plan mode)
2. Write the code to a file
3. Ask for confirmation before writing
4. You approve → file is created

### Example 2: Multi-step project

```
Build a small Flask API with two endpoints: /health and /users
```

The agent will:
- Create project structure
- Write `app.py` with routes
- Add requirements.txt
- Commit to git if repository exists

---

## 🔍 Troubleshooting

### "No API key found"
Run `/config` and set your API key. If you don't have one, get a free key at [freemodel.dev](https://freemodel.dev/invite/FRE-63e7c8c2).

### "Model not found (404)"
The model name doesn't exist at the configured base URL. Check your `model` setting in `/config` and ensure your provider supports that model. Try applying a preset with `p` in the config editor.

### "Permission denied (403)"
Your API key lacks access to the requested model or your quota is exhausted. Check your API key permissions or usage at your provider's dashboard.

### "Session won't resume"
Sessions are only offered if:
- Less than 24 hours old
- Contains at least 2 messages
- `XEROCODEAI_NO_RESUME` is not set

### Config not saving
Config is saved to `~/.xerocodeai/config.json` with permissions `0600`. Ensure the directory is writable.

---

## 📄 License

MIT

---

## 🙏 Credits

Built with ❤️ by the xerocodeai team.
