<div align="center">
# oxi
**CLI binary** — the terminal-based AI coding assistant that ties the oxi workspace together.
[](https://github.com/a7garden/oxi/actions)
[](../LICENSE.md)
</div>
---
## Overview
`oxi` is a terminal-based AI coding assistant. It provides an interactive REPL for chatting with LLMs, a session system for persisting and branching conversations, built-in tools (read, write, edit, bash), a skill/template system, and dynamic extension loading.
## Architecture
```
oxi (CLI harness)
├── oxi-ai — Unified LLM API (streaming, providers, context, tools)
├── oxi-agent — Agent runtime (event loop, tool execution, compaction)
└── oxi-tui — Terminal UI framework (components, rendering, themes)
```
The `oxi` crate itself handles:
- **CLI argument parsing** via `clap`
- **Session management** (JSONL persistence, forking, tree navigation)
- **Settings** (`~/.oxi/settings.toml`)
- **Skill loading** from `~/.oxi/skills/<name>/SKILL.md`
- **Prompt templates** from `~/.oxi/templates/`
- **Package management** (install/uninstall extensions and skills)
- **Extension loading** (dynamic `.so`/`.dylib`/`.dll` shared libraries)
## Installation
```bash
# Build from source
cargo build --release
# The binary is at target/release/oxi
cp target/release/oxi /usr/local/bin/
```
### Requirements
- Rust 1.80+ (edition 2021)
- An API key for at least one LLM provider (see Provider Setup below)
## Quick Start
```bash
# Interactive mode (default)
oxi
# Single prompt (non-interactive)
oxi "Explain Rust ownership in one paragraph"
# Specify provider and model
oxi -p openai -m gpt-4o
# With thinking level
oxi --thinking thorough "Design a REST API for a todo app"
# Load an extension
oxi -e ./my_extension.so
```
### Interactive Commands
Inside the REPL, type `/` followed by a command:
| `/help` | Show available commands |
| `/model` | Show current model |
| `/model <provider/model>` | Switch model (e.g., `openai/gpt-4o`) |
| `/scoped-models` | Set/get models for Ctrl+P cycling |
| `/router` | Configure model router |
| `/router pin <tier>` | Pin router tier (low/medium/high/off) |
| `/router disable` | Switch away from router |
| `/router enable` | Switch to router/auto |
| `/skill` | List skills with active status |
| `/skill <name>` | Activate a skill |
| `/skill off <name>` | Deactivate a skill |
| `/new` | Start a new session |
| `/clone` | Duplicate current session |
| `/resume` | Resume a different session |
| `/fork [id]` | Fork a new session from a previous message |
| `/tree` | Show session tree |
| `/session` | Show session info and stats |
| `/compact` | Compact context |
| `/tools` | List/toggle tools |
| `/extensions` | List extensions & WASM tools |
| `/export [path]` | Export session to HTML |
| `/import <path>` | Import session from JSONL |
| `/share` | Share session as GitHub Gist |
| `/copy` | Copy last response to clipboard |
| `/name <name>` | Set session name |
| `/provider` | Configure API key |
| `/logout` | Remove provider authentication |
| `/settings` | Show current settings |
| `/reload` | Reload settings, theme, and extensions |
| `/changelog` | Show changelog |
| `/hotkeys` | Show key shortcuts |
| `/quit` | Quit oxi |
## Provider Setup
oxi reads API keys from environment variables:
| OpenAI | `OPENAI_API_KEY` |
| Anthropic | `ANTHROPIC_API_KEY` |
| Google | `GOOGLE_API_KEY` |
| DeepSeek | `DEEPSEEK_API_KEY` |
| Mistral | `MISTRAL_API_KEY` |
| Groq | `GROQ_API_KEY` |
| Cerebras | `CEREBRAS_API_KEY` |
| xAI | `XAI_API_KEY` |
| OpenRouter | `OPENROUTER_API_KEY` |
| Azure OpenAI | `AZURE_OPENAI_API_KEY` |
Add them to your shell profile:
```bash
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
```
### Default Model
The default model is `anthropic/claude-sonnet-4-20250514`. Override it in settings:
```toml
# ~/.oxi/settings.toml
default_model = "openai/gpt-4o"
default_provider = "openai"
thinking_level = "standard"
```
Or on the command line:
```bash
oxi -m gpt-4o -p openai
```
## CLI Reference
```
oxi [OPTIONS] [PROMPT]
Arguments:
[PROMPT] Initial prompt (non-interactive mode)
Options:
-p, --provider <PROVIDER> Provider (e.g., anthropic, openai, google)
-m, --model <MODEL> Model (e.g., claude-sonnet-4-20250514, gpt-4o)
-i, --interactive Force interactive mode
--thinking <LEVEL> Thinking level: none, minimal, standard, thorough
-e, --extension <PATH> Load extension from shared library (repeatable)
-h, --help Print help
-V, --version Print version
Subcommands:
sessions List all sessions
tree [SESSION_ID] Show session tree structure
fork <PARENT_ID> <ENTRY_ID> Fork a session from a specific entry
delete <SESSION_ID> Delete a session
export [SESSION_ID] Export session to HTML
import <PATH> Import session from JSONL
share [SESSION_ID] Share session as GitHub Gist
pkg install <SOURCE> Install a package
pkg list List installed packages
pkg uninstall <NAME> Uninstall a package
config show Show current settings
config set <KEY> <VALUE> Set a config value
config enable <TYPE> <NAME> Enable a resource
config disable <TYPE> <NAME> Disable a resource
models [--provider] List available models
setup [--reset] Run setup wizard
reset [--yes] Reset to factory defaults
ext install <SOURCE> Install WASM extension
ext list List extensions
ext remove <NAME> Remove extension
```
## Settings
Settings are stored at `~/.oxi/settings.toml`:
```toml
thinking_level = "standard" # none, minimal, standard, thorough
theme = "default" # TUI color theme
default_model = "anthropic/claude-sonnet-4-20250514"
default_provider = "anthropic"
max_tokens = 4096
temperature = 0.7
session_history_size = 100
stream_responses = true
```
## Skills
Skills are markdown files that inject context into the system prompt. Place them in `~/.oxi/skills/<name>/SKILL.md`:
```
~/.oxi/skills/
├── rust-expert/
│ └── SKILL.md # Activated with /skill rust-expert
└── code-review/
└── SKILL.md # Activated with /skill code-review
```
## Templates
Prompt templates support variable substitution. Place `.md` files in `~/.oxi/templates/`:
```markdown
Review the following {{language}} code for bugs and improvements:
{{code}}
```
Use with `/template review language=Rust code="fn main() {}"`.
## Sessions
Sessions are persisted as JSONL files in `~/.oxi/sessions/`. Each session is a tree of entries that can be listed, inspected, and forked:
```bash
# List sessions
oxi sessions
# View session tree
oxi tree
# Fork from a specific entry
oxi fork <parent-session-id> <entry-id>
# Delete a session
oxi delete <session-id>
```
## Extensions
Extensions are dynamically loaded shared libraries that register custom tools with the agent:
```bash
oxi -e ./my_custom_tool.so
```
Extensions implement the `AgentTool` trait from `oxi-agent` and are registered at startup.
## License
[MIT](../LICENSE.md)