RxyCode is a general-purpose AI agent built on LangGraph with a hierarchical
plan-and-execute architecture. It decomposes complex tasks into subtasks,
executes them with a safe tool orchestrator, validates results, and synthesizes
a final answer — all streamed live to an OpenTUI terminal UI (Ink fallback available).

Why RxyCode?

• Anti-hallucination — A dedicated validator checks tool results against
  the original goal before reporting success
• Plan & Execute — Hierarchical task decomposition with dependency-aware
  parallel execution, not a linear ReAct loop
• Safe by default — Risk-level classification, write whitelist, approval
  dialogs, and full audit trail
• Blazing fast — Three-level cache (exact hash + semantic similarity +
  Provider KV), 50 ms token batching, fast-reply path for simple queries
• Beautiful TUI — OpenTUI/React/TypeScript frontend (default) with
  streaming output, ScrollBox chat, native textarea, and OpenCode-style panels;
  Bun is auto-installed by the one-command installer when missing; Ink remains
  as RXYCODE_TUI=ink fallback
• 30+ tools — File ops, shell, web search/fetch, git, RAG, MCP, LSP, and more

Quick Start

Prerequisites

Option 1: One-command install (recommended)

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/xin-yi33/RxyCode/v1.2.4/install.ps1 | iex"
rxycode

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/xin-yi33/RxyCode/v1.2.4/install.sh | sh
rxycode

The installer bootstraps uv (if needed), creates an isolated tool
environment, and installs the pinned v1.2.4 release. No manual clone
required.

Downloads: only the latest release (v1.2.4) publishes installable
wheel/sdist assets. Older GitHub Releases keep release notes but do not
offer binary downloads.

Option 2: Run once with uv

uvx --from "git+https://github.com/xin-yi33/[email protected]" rxycode

Option 3: Permanent install

uv tool install --force "git+https://github.com/xin-yi33/[email protected]"
rxycode

Option 4: From source

git clone https://github.com/xin-yi33/RxyCode.git
cd RxyCode
python -m pip install -e .
rxycode

Option 5: Docker

cp .env.example .env   # Set OPENAI_API_KEY and RXYCODE_API_TOKEN
docker compose up -d api       # API server (loopback only)
docker compose run --rm tui    # Interactive TUI (needs TTY)

First launch

1. Run rxycode — the TUI opens even without a model configured
2. If no models are configured yet, the TUI detects the empty list, shows a welcome hint, and automatically opens the /addmodel wizard (credential input is masked)
3. If one or more models are already configured, there is no extra hint and no auto dialog
4. Start chatting! Type your request in natural language

Architecture

User Input
    │
    ▼
AgentV2 (core/agent_v2.py)
    │
    ├── Simple query  →  Fast path (single LLM call + cache check)
    ├── Multi-task    →  Sub-agents (parallel)
    ├── Compose       →  Plan + Build
    └── Complex       →  LangGraph Pipeline:
                              │
                 goal_planner → decomposer → executor → ToolOrchestrator
                                                → evidence → validator
                                                            → synthesizer

Streaming Pipeline

Backend (Python)                          Frontend (TypeScript/OpenTUI)
─────────────────                         ──────────────────────────────
_raw_stream()                              chatApi.ts / App.tsx
  │                                          │
  ├── cache_control injection                fetch /chat/stream (SSE)
  │                                          │
  ├── OpenAI async stream                    parse SSE events:
  │   ├── reasoning_content → reasoning       ├── progress/reasoning/plan/step
  │   ├── content token → stream_token        ├── token → live assistant stream
  │   └── tool_calls delta                    ├── tool_call/tool_result
  │                                           ├── approval → ApprovalDialog
  └── StreamTUI → asyncio.Queue → SSE         └── final/done → terminal state

Modes

Directory Structure

Testing

Frontend (TypeScript)

cd frontend && npm test    # 28 files / 158 tests

Backend (Python)

python -m pytest tests -m "not live and not pty and not serial" -n 2 --dist loadscope -q
python -m pytest tests -m "serial and not live and not pty" -n 0 -q
# 2319 deterministic tests passed

Configuration

Configuration is stored at ~/.rxycode/config.yaml:

cache:
  enabled: true
  prompt_prefix_cache: true   # Enable provider-side KV cache
  ttl: 3600

models:
  - name: deepseek-v4-flash
    provider: openai
    api_key: <your-key>        # Stored outside the repo, never committed
    base_url: https://api.deepseek.com

Use /addmodel in the TUI for a guided setup wizard.

Commands

Shortcuts

Version History

See CHANGELOG.md for the full change history.

License

MIT © RxyCode contributors