xerocodeai 0.3.0

AI coding assistant — REPL + agent loop powered by OpenAI-compatible models

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

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 — no credit card required.

2. Configure xerocodeai

Run the command:

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:

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:

export XEROCODEAI_PROFILE="yolo"

Or force yes for all prompts:

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:

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.

"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.