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).
- 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=inkfallback - 30+ tools — File ops, shell, web search/fetch, git, RAG, MCP, LSP, and more
| Requirement | Version | Notes |
|---|---|---|
| Python | 3.10+ | Backend runtime |
| Bun | latest | Auto-installed by the one-command installer when missing (OpenTUI) |
| Node.js | 20+ | Optional Ink fallback (RXYCODE_TUI=ink) |
| OpenAI-compatible API key | — | Any provider (OpenAI, DeepSeek, etc.) |
Windows PowerShell:
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/xin-yi33/RxyCode/v1.2.5/install.ps1 | iex"
rxycodemacOS / Linux:
curl -fsSL https://raw.githubusercontent.com/xin-yi33/RxyCode/v1.2.5/install.sh | sh
rxycodeThe installer bootstraps uv (if needed), creates an isolated tool
environment, and installs the pinned v1.2.5 release. No manual clone
required.
Downloads: only the latest release (v1.2.5) publishes installable
wheel/sdist assets. Older GitHub Releases keep release notes but do not
offer binary downloads.
uvx --from "git+https://github.com/xin-yi33/RxyCode.git@v1.2.5" rxycodeuv tool install --force "git+https://github.com/xin-yi33/RxyCode.git@v1.2.5"
rxycodegit clone https://github.com/xin-yi33/RxyCode.git
cd RxyCode
python -m pip install -e .
rxycodecp .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)- Run
rxycode— the TUI opens even without a model configured - If no models are configured yet, the TUI detects the empty list, shows a welcome hint, and automatically opens the
/addmodelwizard (credential input is masked) - If one or more models are already configured, there is no extra hint and no auto dialog
- Start chatting! Type your request in natural language
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
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
| Mode | Command | Behavior |
|---|---|---|
| Build | /build |
Full pipeline: plan → decompose → execute → validate → synthesize |
| Plan | /plan |
Read-only analysis and planning, no file modifications |
| Compose | /compose |
Plan + build with simplified pipeline |
| Directory | Purpose |
|---|---|
core/ |
AgentV2, LangGraph graph, state, prompts, UsageTrackingLLM |
planning/ |
Goal refiner, task decomposer |
execution/ |
Executor, tool orchestrator |
validation/ |
Validator, re-planner |
synthesis/ |
Output synthesizer |
frontend/opentui-app/ |
Default OpenTUI/React TUI (Bun + React 19) |
frontend/ |
Ink/React TUI fallback (RXYCODE_TUI=ink) |
tools/ |
30+ built-in tools (read, write, edit, bash, grep, web, git, ...) |
memory/ |
Tiered memory (short-term, long-term, user, search) |
cache/ |
Three-level cache (exact + semantic + Provider KV) |
config/ |
Configuration management (~/.rxycode/config.yaml) |
rag/ |
Codebase vector search (chunking, embedding, cosine) |
scheduler/ |
Cron-like prompt scheduling |
recovery/ |
Error recovery with retry logic |
mcp/ |
MCP server integration |
lsp/ |
LSP integration (experimental) |
safety/ |
Risk levels, approval, write whitelist, audit |
evals/ |
Evaluation harness (success rate, LLM-as-judge) |
tests/ |
Python test suite (2319 deterministic tests) |
cd frontend && npm test # 28 files / 158 testspython -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 passedConfiguration 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.comUse /addmodel in the TUI for a guided setup wizard.
| Command | Description |
|---|---|
/help |
Show all available commands |
/addmodel |
Add a new model |
/models |
List all models |
/model <name> |
Switch model |
/build /plan /compose |
Switch work mode |
/clear |
Clear conversation context |
/memory add/list/search |
Memory management |
/queue add/run |
Task queue |
/cache |
View cache statistics |
/language |
Switch language |
/thinking |
Toggle thinking panel |
| Shortcut | Action |
|---|---|
Tab |
Switch work mode |
Ctrl+S |
Send message |
Ctrl+X |
Cancel current operation |
Ctrl+? |
Show help |
Ctrl+E |
External editor |
Ctrl+C |
Quit |
| Version | Date | Highlights |
|---|---|---|
| v0.3.3 | 2025-12 | Initial release: ReAct + anti-hallucination + MCP |
| v1.0.0 | 2026-06 | LangGraph rewrite: plan-and-execute, 24+ tools, tiered memory |
| v1.1.0 | 2026-07 | Ink TUI, SSE streaming, Docker, CI/CD, one-command installers |
| v1.2.0 | 2026-07 | Frontend rewrite: OpenTUI default TUI (Ink fallback), settings parity, safer Ctrl+C, plan hints, autoCompact |
| v1.2.1 | 2026-07 | Package fix: ship OpenTUI sources in the installable wheel |
| v1.2.2 | 2026-07 | Auto-install Bun + OpenTUI deps; empty-model welcome hint + auto /addmodel |
| v1.2.3 | 2026-07 | OpenCode add-model: presets, discover, preset multi-select batch onboard, /model provider groups |
| v1.2.4 | 2026-08 | Add-model polish + slash Enter; Phase 1 eval harness; Phase 2 typed protocol + TS client |
| v1.2.5 | 2026-08 | Phase A model adaptation layer; Phase 2 completion (stdio transport, request routing, lazy imports, API thinning) |
See CHANGELOG.md for the full change history.
MIT © RxyCode contributors