Metadata-Version: 2.4
Name: vaal-code
Version: 0.7.0
Summary: AI coding agent CLI — local LLMs via Ollama, AirLLM, or cloud models via API
License: MIT
Project-URL: Homepage, https://e-e.tools/vaal
Project-URL: Repository, https://github.com/0xE666/vaal
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.25.0
Requires-Dist: rich>=13.0.0
Provides-Extra: voice
Requires-Dist: SpeechRecognition; extra == "voice"
Provides-Extra: airllm
Requires-Dist: airllm; extra == "airllm"
Requires-Dist: huggingface_hub; extra == "airllm"

# Vaal

AI coding agent CLI. Runs local LLMs via Ollama or cloud models via API. Named after the Vaal Orb from Path of Exile.

## Install

```bash
git clone https://github.com/0xE666/vaal.git
cd vaal
python install.py
```

That's it. `vaal` is now available as a command from anywhere, just like `claude`.

Or manually:

```bash
pip install -e .
```

## Quick Start

```bash
# With Ollama (free, local)
vaal

# With Claude
vaal -m anthropic:claude-sonnet-4-20250514

# With OpenAI
vaal -m openai:gpt-4o
```

On first run with a cloud model, use `/login` to add your API key:

```
/login anthropic sk-ant-api03-your-key-here
/login openai sk-your-key-here
```

Or create a vaal account at [e-e.tools/vaal](https://e-e.tools/vaal):

```
/register
```

## Features

- **45 tools** — bash, file read/write/edit, git, grep, glob, web search, agents, notebooks, and more
- **Subagents** — spawn background agents (explore, plan, verify, code-review) that work in parallel
- **80+ slash commands** — `/commit`, `/test`, `/pr`, `/diff`, `/pin`, `/remote`, `/plugin`, and more
- **Multi-provider** — Ollama, AirLLM (local 70B+ on 4GB VRAM), Anthropic, OpenAI, Groq, OpenRouter, DeepSeek, Together
- **Self-repair** — catches its own crashes, asks the LLM to fix the bug, patches itself
- **Remote control** — control vaal from a browser at e-e.tools/vaal
- **Plugins** — create custom tools with `/plugin create` or let the LLM generate them
- **Tab completion** — file paths auto-complete on Tab
- **Persistent history** — Up arrow recalls prompts across sessions

## Providers

| Provider | Auth | Example |
|----------|------|---------|
| Ollama | None (local) | `vaal -m qwen3:8b` |
| AirLLM | None (local, CUDA) | `vaal -m airllm:Qwen/Qwen2.5-14B-Instruct` |
| Anthropic | API key or Max/Pro OAuth | `vaal -m anthropic:claude-opus-4-6` |
| OpenAI | API key | `vaal -m openai:gpt-4o` |
| Groq | API key | `vaal -m groq:llama-3.3-70b-versatile` |
| OpenRouter | API key | `vaal -m openrouter:anthropic/claude-sonnet-4` |
| DeepSeek | API key | `vaal -m deepseek:deepseek-chat` |
| Together | API key | `vaal -m together:meta-llama/Llama-3.3-70B` |

## Key Commands

```
/help          — All commands
/login         — Add API key
/register      — Create vaal account
/commit        — Auto-generate commit message
/test          — Run tests, auto-fix failures
/pr            — Create pull request
/pin <file>    — Keep file in context
/remote        — Control from browser
/plugin create — Create custom tools
/effort        — Set inference level
/doctor        — System diagnostics
```

## AirLLM — Run 70B Models Locally

Run any HuggingFace model on low-VRAM GPUs via layer-by-layer inference:

```bash
pip install vaal-code[airllm]      # install AirLLM support

vaal
/pull airllm:Qwen/Qwen2.5-14B-Instruct          # download model
/model airllm:Qwen/Qwen2.5-14B-Instruct         # switch to it

# With 4-bit compression for larger models (72B on 12GB VRAM):
/pull airllm:Qwen/Qwen2.5-72B-Instruct
/model airllm:Qwen/Qwen2.5-72B-Instruct:4bit
```

Set download location in `~/.vaal/config.json`:
```json
{ "airllm": { "layer_shards_saving_path": "D:/models" } }
```

## Requirements

- Python 3.11+
- httpx, rich (auto-installed)
- Ollama (optional, for local models via Ollama)
- CUDA GPU + `pip install vaal-code[airllm]` (optional, for AirLLM local inference)
- Git (optional, for git commands)
