rtxclaw.ai

Run it now: git clone … && cd rtxclaw && ./rtxclaw — the launcher creates .venv/, installs dependencies, and starts the TUI. Or pip install rtxclaw && rtxclaw — the first-run wizard walks you through the LLM endpoint and model choice.

Install

pip install rtxclaw

That puts a rtxclaw command on your PATH. Run it once with no arguments — the first-run wizard walks you through the LLM endpoint, model, and (optionally) Telegram, then brings the gateway up itself. Three steps and you're in the TUI:

pip install rtxclaw → rtxclaw → answer the wizard → done.

Optional extras:

From a clone (for development)

git clone … && cd rtxclaw && ./rtxclaw — the launcher creates .venv/, runs an editable pip install -e ., and starts the TUI.

Run the gateway, orchestrator and WebUI together

pip install "rtxclaw[web]"     # the WebUI lives in the [web] extra
python -m rtxclaw.serve        # foreground: Ctrl+C stops the whole stack

serve brings all three components up and prints one line per component:

START orchestrator 8099 pid=1234 http=200
START gateway 8100 pid=1235 http=200
START web 8110 pid=1236 http=200
WebUI http://127.0.0.1:8110  (Ctrl+C stops the stack; --detach keeps it running after this shell exits)

python -m rtxclaw.serve --detach   # background; survives the shell closing
python -m rtxclaw.serve status     # one PASS/FAIL line per component
python -m rtxclaw.serve stop       # shut the stack down
python -m rtxclaw.serve --no-web   # backend roles only (no [web] extra needed)

The same entry point is installed as the rtxclaw-serve console script, and python -m rtxclaw is an alias. There is deliberately no service supervisor and no restart loop: a component that dies is reported by name, never respawned.

Inside a source checkout, rtxclaw.bat / rtxclaw-stop.bat / rtxclaw-status.bat wrap these same three commands for Windows.

Core Packages

Modular packages under src/ — installed as pip install rtxclaw:

Extras

• [full] — trafilatura (web-fetch), markitdown (PDF/DOCX), yt-dlp + youtube-transcript-api (YouTube), imageio-ffmpeg (voice-note transcode)
• [web] — Flask for the browser chat frontend (waitress on Windows, gunicorn on POSIX)
• [stt] — faster-whisper (CPU-only STT for Telegram voice)

Memory index maintenance

Normal maintenance is automatic: remember indexes immediately after a successful write, memory search lazily indexes detected drift before querying, and the gateway heartbeat asks the persistent memory service to reindex only when needed. The Markdown files remain the source of truth; memory.db is a rebuildable search index.

Use the operator CLI when checking or repairing an agent explicitly:

# Show file/chunk/vector counts, index scope, and whether drift is pending.
rtxclaw memory status --agent codex

# Safe incremental pass: changed files and missing vectors only.
rtxclaw memory index --agent codex

# Rebuild chunks/FTS/vectors, retaining reusable embedding-cache rows.
rtxclaw memory index --agent codex --force

# Also discard the cache and call the configured embedding provider again.
rtxclaw memory index --agent codex --reembed

Start with the incremental command. --force rebuilds only the derived index; it does not delete the Markdown memories. --reembed is the expensive recovery path for a changed model or poisoned cache and requires a working embedding provider.

rtxclaw is the cypherpunk version of inference.

It exists to empower the user to have total control over their data and ideas, without the hassle of endless configuration or requiring deep open-source model knowledge just to get useful work done.

This project starts from a hard truth: the AI industry is underinvesting in infrastructure and degrading model quality to keep up with demand. Decisions like blocking OpenClaw from the Max plan and forcing heavy API costs on users reinforce the view that AI companies are sucking people and companies' ideas like the Matrix uses human crops for creativity and for studying human thought processes.

That is the opposite of sovereignty.

The current model asks users and companies to pour their private context, internal reasoning, product ideas, and operational intelligence into centralized AI systems they do not control. In return, they get rising costs, shrinking access, degraded quality under load, and dependence on infrastructure decisions made by someone else.

And the risk is not theoretical.

The imminent Taiwan conflict will create heavy shocks to current business. Any company relying on AI will have no option but to pay the price of neoclouds if supply chains seize up and centralized inference tightens further. Businesses that chose not to build on-prem infrastructure, or at least retain the option, will be trapped into paying whatever the market demands.

rtxclaw is the answer to that trap.

rtxclaw is a custom-built agent system that adapts to the available inference capacity by creating tailored agents for each hardware profile, from a modest RTX 3060 to RTX 3090, RTX 4090, RTX 5090, A6000-class workstations, and up to advanced rented neocloud GPUs on platforms like Vast.ai.

Instead of forcing every task through one oversized, expensive, centralized stack, rtxclaw rightsizes inference to the real job:

• small agents on cheap local hardware
• stronger agents on workstations
• burst agents on rented neocloud GPUs
• flexible routing based on actual available capacity
• model selection based on task value, latency, and hardware envelope
• agent behavior shaped around the realities of the machine it runs on

Agents can be spawned in seconds using the right-sizing capacity for each task, reducing the cost of AI while increasing resilience, performance, and control.

Why rtxclaw exists

Most AI products are built around a hidden assumption: the user should adapt to the vendor.

The vendor chooses the models.
The vendor chooses the pricing.
The vendor chooses when quality gets degraded.
The vendor chooses which products get blocked.
The vendor chooses which workloads are too expensive.
The vendor chooses whether your use case is welcome.

rtxclaw rejects that model.

The intelligence layer of a company is too important to outsource blindly. Your prompts are not just prompts. They are product direction, customer knowledge, internal process, strategy, failure modes, experimentation, and judgment in raw form. If your AI stack is not sovereign, your cognition stack is not sovereign.

Core Principles

• Own the data: Single-file session logs stored locally on your machine.
• Own the ideas: No outbound telemetry leaks.
• Own the inference path: Seamless fallback between local vLLM, private workstations, and cloud models.
• Instant Responsiveness: < 5ms submission ACKs on all inputs, < 2ms UI cache reads from SQLite.
• Zero Configuration Sprawl: Single .jsonl session files, extensible JSON tool containers, zero sidecars.
• Clean Protocol Boundaries: ACP for IDE control (North-South), A2A for multi-agent swarms (East-West).
• Cancel Scopes You Can Reason About: Abort one turn and only that turn dies; abort a subagent and only that subagent terminates.

Architecture Overview

The canonical system architecture is documented in detail in the Technical Specifications.

Runtime: rtxclaw gateway start brings up the south orchestrator (:8099) then the north gateway (:8100). rtxclaw gateway stop stops both.

flowchart TD
    Clients["Multi-Interface Clients<br/><b>WebUI • Telegram • TUI • IDE (via ACP)</b>"]
    
    Gateway["rtxclaw_gateway (North)<br/>• Ingress Auth & Multi-Source Queue (<5ms ACK)<br/>• Fast SQLite Cache Server (<2ms)<br/>• Multi-Subscriber SSE Streamer"]
    
    Orchestrator["rtxclaw_orchestrator (South)<br/>• Turn & Round State Machine<br/>• Multi-Modal Engine Adapters (CLI, ACP, A2A)<br/>• Tool Dispatch & AI Model Telemetry"]
    
    Storage["rtxclaw_session (Storage Engine)<br/>• Single-File Ledger (<session_id>.jsonl)<br/>• Instant SQLite Cache (sessions.db)"]
    
    Clients -->|"1. Submit Prompts & Subscribe Stream"| Gateway
    Gateway -->|"2. Priority Ingress Queue (FIFO)"| Orchestrator
    Orchestrator -->|"3. Append Events, Row Markers, & Project Cache"| Storage
    Gateway -.->|"4. Fast REST Reads & SSE Tails"| Storage

1. Storage Tier (rtxclaw_session)

• Single-File Ledger (<session_id>.jsonl): Exactly 1 immutable, append-only file per session. Zero loose sidecars.
• Materialized SQLite Cache (sessions.db): Atomic single-row reads for instant UI loading (< 2ms).
• Extensible JSON Containers (tools_state_json): Dynamic tool state updates (Kanban, Todos, Canvas) via json_set() with zero database schema migrations.
• Row Range Markers: Exact [start_row_idx, end_row_idx] recorded for every turn and every AI model call.

2. Multi-Modal Execution (rtxclaw_orchestrator)

• CLI Adapter: Invokes subprocess CLI tools (agy, claude, codex) and wraps them into standard message envelopes.
• ACP Adapter: Interacts with external IDEs (Cursor, Zed) via JSON-RPC 2.0.
• A2A Adapter: Coordinates autonomous subagents via native a2a/v1 message envelopes.
• AI Telemetry Collector: Captures TTFT, generation speed (tokens/sec), routing overhead, token volume, and cost ($) into the ai_generations table.

3. Edge Membrane (rtxclaw_gateway)

• Session Ingress Queue: Immediate < 5ms submission ACK for WebUI, Telegram, TUI, A2A subagents, and schedulers.
• Priority Intake: Priority 0 (Control) $\rightarrow$ Priority 1 (Subagent Returns) $\rightarrow$ Priority 2 (User Prompts) $\rightarrow$ Priority 3 (System Nudges).
• Row-Indexed SSE Streaming: Clients seek directly to any row (GET /stream?from=<row_idx>) with zero token loss and zero duplicate frames.

Documentation Roadmap

The full system documentation is organized into 10 domain directories matching the WebUI tabs:

• Requirements (WHAT): Product specifications, functional requirements (FR-01 to FR-11), and quality SLAs.
• Technical Specifications (HOW): Authoritative architecture contracts, Mermaid diagrams, event wire schemas, and SQLite table definitions.
• Implementation Plans (WHEN): Phase-by-phase engineering execution roadmaps and automated test verification suites.