oxicode

A terminal-based AI coding assistant built in Rust.

A Rust port of pi by Mario Zechner. Multi-provider · Streaming-first · Extensible · Session persistence

Install · Quick start · Architecture · Configuration · Oxi ecosystem · Contributing · Changelog

---

Table of contents

• Highlights
• Install
• Quick start
• Architecture
• Oxi ecosystem
• Oxi Foundation host
• Configuration
• CLI reference
• Built-in skills
• Development
• Contributing
• License

Highlights

oxicode is a Rust port of pi, re-implementing its core architecture — unified LLM API, agent runtime, tool calling, terminal UI, and session persistence — in idiomatic Rust with Tokio, Ratatui, and Serde.

It brings the power of LLM-based coding assistants directly to your terminal — fast, private, and fully under your control.

Feature	Description
🌐 Multi-provider	OpenAI, Anthropic, Google, DeepSeek, Mistral, Groq, Cerebras, xAI, OpenRouter, Azure
⚡ Streaming-first	Real-time token streaming with thinking/reasoning support
🔧 Tool calling	Built-in read, write, edit, bash, grep, find — plus extensible trait system
🖥️ Interactive TUI	Component-based terminal UI with themes, markdown rendering, and image support
🌳 Session system	Persistent conversations with branching, forking, and JSONL storage
🧩 Skill system	Pluggable prompt skills (brainstorming, deep research, code review, etc.)
🔌 Extensions	Dynamically load native .so/.dylib/.dll or WASM plugins
📦 Package manager	Install, update, and manage skill/extension packages
🤖 Multi-agent SDK	Build multi-agent pipelines with the oxicode-sdk builder pattern

Install

cargo install (any Rust toolchain ≥ 1.96):

cargo install oxicode-cli

cargo binstall (10-100x faster — uses prebuilt binary from the GitHub release):

cargo install cargo-binstall
cargo binstall oxicode-cli

Pre-built binary (macOS Apple Silicon):

# aarch64-apple-darwin
curl -fsSL https://github.com/project-oxi/oxicode/releases/latest/download/aarch64-apple-darwin.tar.gz \
  | tar xz -C /usr/local/bin

Or download from the Releases page. Each release ships with SHA256SUMS for integrity verification.

Build from source (last resort):

git clone https://github.com/project-oxi/oxicode.git
cd oxicode && cargo build --release
cp target/release/oxicode /usr/local/bin/

Built-in browser. oxicode ships with a pure-Rust headless browser (oxibrowser) by default — the agent can browse, screenshot, and read web pages with no Chrome/Playwright dependency. read <url> fetches static page bodies as reader-mode markdown; browse <url> drives the full browser (JavaScript, screenshots, vision). To build without it (smaller binary, no browser tools): cargo install oxicode-cli --no-default-features --features self-update.

Verify a downloaded binary

curl -fsSL https://github.com/project-oxi/oxicode/releases/latest/download/SHA256SUMS -o SHA256SUMS
sha256sum -c SHA256SUMS 2>/dev/null | grep aarch64-apple-darwin

Quick start

Configure

# Set your API key (Anthropic, OpenAI, Google, etc.)
export ANTHROPIC_API_KEY="sk-ant-..."

Run

# Interactive mode (default)
oxicode

# Single prompt
oxicode "Explain Rust ownership"

# Specify provider and model
oxicode -p openai -m gpt-4o "Design a REST API"

That's it. No config files required — oxicode works out of the box.

Architecture

oxicode is a multi-crate Rust workspace designed for modularity:

graph LR
    A[oxicode-cli] --> B[oxicode-sdk]
    A --> C[oxicode-vtui]
    B --> E[oxicode-agent]
    E --> F[oxicode-ai]

Loading

Crate	Purpose
oxicode-ai	Unified LLM API — 8 providers, streaming, tool calling, compaction
oxicode-agent	Agent runtime — tool-calling loop, event system, MCP client
oxicode-vtui	Terminal UI framework — ratatui widgets, theme registry, markdown, vim engine
oxicode-sdk	Multi-agent SDK — agent groups, message bus, port-based adapters, builder pattern
oxicode-cli	CLI binary — ties everything together (TUI + RPC + port composition root)

Oxi ecosystem

oxicode owns the terminal coding runtime and SDK. It uses oxibrain for durable local memory, works with oxios when orchestration is needed, and can act on the shared plain-text vault managed by oximemo. The integrations use public CLI or client contracts; they do not share storage internals.

Oxi Foundation host

oxicode is an Oxi Foundation v1 host. It resolves provider profiles and packages from a shared installation under ~/.oxi/foundation/v1/, treats oxibrain as its only durable memory authority, and keeps its own access policy, sandbox, and tool approvals intact. Foundation packages declare abstract capabilities (workspace.read, shell.execute, brain.query, …); oxicode maps each declared requirement to its existing policy gate. A verified foundation package is not automatically authorized.

~/.oxi/foundation/v1/
├── foundation.json          # schema version + host compatibility
├── profiles.json            # non-secret provider/model profiles
├── packages.lock            # immutable resolved package records
└── packages/<sha256>/       # verified immutable package content

Credentials live in the OS Keychain. No profile, lockfile, log, or diagnostic carries a secret value. The contract is documented in docs/superpowers/specs/2026-08-17-oxi-foundation-contract.md; the host role is part of a three-host agreement with oxibrain (durable memory) and oxios (orchestration).

If no Foundation installation is present, oxicode runs in offline mode with environment-variable credentials only. It reaches oxibrain through its agent-first CLI or a caller-owned oxibrain admin serve --stdio child; when the brain is unavailable, memory tools degrade to typed unavailable errors — there is no local fallback store. Existing ~/.oxicode/auth.json credentials can be migrated one-time into the Keychain via oxicode config migrate-foundation, and legacy ~/.oxicode/memory/items.jsonl memories via oxicode migrate brain.

Configuration

Settings are layered — later layers override earlier ones:

defaults → <canonical home>/settings.{toml,json} → .oxicode/settings.toml → env vars → CLI flags

The canonical home is $OXICODE_HOME, else $OXI_HOME/oxicode, else ~/.oxi/oxicode. Pre-unified-layout installs under the legacy ~/.oxicode/ keep working: readers fall back to it read-only until you run oxicode migrate home (journaled, resumable, copy-only; inspect the plan first with oxicode migrate home --dry-run, and check the layout with oxicode doctor).

Example <canonical home>/settings.toml:

default_model = "anthropic/claude-sonnet-4-20250514"
default_provider = "anthropic"
thinking_level = "medium"
theme = "default"
temperature = 0.7
max_tokens = 4096
auto_compaction = true

Environment variable overrides:

Variable	Setting
OXICODE_MODEL	default_model
OXICODE_PROVIDER	default_provider
OXICODE_THEME	theme
OXICODE_TEMPERATURE	default_temperature
OXICODE_MAX_TOKENS	max_response_tokens

CLI Reference

oxicode [OPTIONS] [PROMPT]

Options:
  -p, --provider <PROVIDER>    Provider (anthropic, openai, google, ...)
  -m, --model <MODEL>          Model (claude-sonnet-4-20250514, gpt-4o, ...)
  -i, --interactive            Force interactive mode
      --thinking <LEVEL>       off, minimal, low, medium, high, xhigh
  -e, --extension <PATH>       Load extension (repeatable)
  -h, --help                   Print help
  -V, --version                Print version

Commands:
  sessions                     List all sessions
  tree [SESSION_ID]            Show session tree
  fork <PARENT> <ENTRY>        Fork a session
  delete <SESSION>             Delete a session
  pkg install <SOURCE>         Install a package
  pkg list                     List packages
  config show                  Show configuration
  config set <KEY> <VALUE>     Set a configuration value

Built-in Skills

Skill	Purpose
Autonomous Loop	Self-correcting design→implement→verify cycle
Brainstorming	Collaborative ideation with multi-approach comparison
Deep Research	Investigation, analysis, and design documentation
Reviewer	Multi-axis code review
Super Review	Deep system-level review
Planner	Implementation planning with dependency batching
Scout	Fast codebase reconnaissance and structure analysis
Design Farmer	Design system construction (colors, tokens, a11y)
Playwright CLI	Browser automation via Playwright
Worktree	Git worktree management

Development

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo nextest run --workspace
cargo test --workspace --doc
cargo audit
cargo deny check

Contributing

See CONTRIBUTING.md for the full development guide and AGENTS.md for the project architecture and quality gates.

FAQ

Which providers are supported?

OpenAI, Anthropic, Google, DeepSeek, Mistral, Groq, Cerebras, xAI, OpenRouter, and Azure OpenAI. Set the relevant API_KEY environment variable and use -p <provider> to select one.

Can I use oxicode as a library?

Yes. Each crate is published independently: oxicode-ai (LLM API), oxicode-agent (agent runtime), oxicode-vtui (terminal UI), oxicode-sdk (multi-agent SDK). See individual crate READMEs for details.

How do sessions work?

Sessions are stored as append-only JSONL files in the canonical home's sessions/ directory (default ~/.oxi/oxicode/sessions/). Each session is a tree — you can fork from any point to explore alternative paths without losing history. Use oxicode sessions to list, oxicode tree to inspect, and oxicode fork to branch.

Does oxicode send my code to third parties?

oxicode only communicates with the LLM provider you select. No telemetry, no analytics, no third-party data collection. Your code stays between you and your chosen provider.

Attribution

oxicode is a Rust port of pi by Mario Zechner. The architectural design, provider abstraction, tool system, streaming events, and session tree are derived from the original pi project (MIT License). See NOTICE.md for details.

License

MIT © 2025 Mario Zechner, 2025–2026 oxicode contributors

Sponsorship

oxicode is developed and maintained by volunteers. If oxicode saves you time or makes your workflow better, consider sponsoring the project to fund continued work on providers, the agent loop, and the TUI.