Metadata-Version: 2.4
Name: rtxclaw
Version: 0.12.0
Summary: Sovereign-inference TUI chat against an OpenAI-compatible vLLM endpoint.
Author: rtxclaw.ai
License-Expression: MIT
Keywords: llm,tui,vllm,agent,acp,sovereign-inference
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: textual>=0.85
Requires-Dist: httpx>=0.27
Requires-Dist: aiohttp>=3.9
Requires-Dist: rich>=13.0
Requires-Dist: openai>=1.0
Requires-Dist: sqlite-vec>=0.1.6
Requires-Dist: mcp>=1.0
Requires-Dist: agent-client-protocol>=0.9
Requires-Dist: hypercorn>=0.17
Requires-Dist: starlette>=0.40
Requires-Dist: sse-starlette>=2.1
Provides-Extra: full
Requires-Dist: trafilatura>=2.0; extra == "full"
Requires-Dist: markitdown[pdf]>=0.0.1a3; extra == "full"
Requires-Dist: markitdown-mcp>=0.0.1a3; extra == "full"
Requires-Dist: imageio-ffmpeg>=0.5.1; extra == "full"
Requires-Dist: yt-dlp>=2024.10.7; extra == "full"
Requires-Dist: youtube-transcript-api>=1.0; extra == "full"
Provides-Extra: web
Requires-Dist: flask>=3.1.3; extra == "web"
Requires-Dist: requests>=2.32; extra == "web"
Requires-Dist: gunicorn>=23.0; extra == "web"
Provides-Extra: stt
Requires-Dist: faster-whisper<2,>=1.0; extra == "stt"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Requires-Dist: telethon>=1.36; extra == "dev"
Requires-Dist: gTTS>=2.4; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

| Install command | What you get |
|---|---|
| `pip install rtxclaw` | Lean core — TUI + agent gateway + MCP client + memory |
| `pip install rtxclaw[full]` | Add PDF/DOCX/YouTube/web-extraction tools |
| `pip install rtxclaw[web]` | Add [browser chat frontend](#browser-frontend) |
| `pip install rtxclaw[stt]` | Add local Fast Whisper speech-to-text (CPU) |

### From a clone (for development)

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

## Packages

Nine sibling packages under `src/` — installed as `pip install rtxclaw`:

| Package | Role |
|---|---|
| `rtxclaw_tui` | Textual TUI — the primary interface |
| `rtxclaw_agent` | Agent gateway + orchestrator + ACP backend |
| `rtxclaw_core` | Turn loop, tools, system prompt, routing |
| `rtxclaw_acp` | Agent Client Protocol (JSON-RPC) framing + transports |
| `rtxclaw_mcp` | Bundled MCP servers (memory, web, delegate, youtube) |
| `rtxclaw_memory` | SQLite-vec memory/index/embed/rerank |
| `rtxclaw_telegram` | Telegram bot (group-chat, voice, commands) |
| `rtxclaw_web` | Browser web frontend (WS → event stream renderer) |
| `rtxclaw_realtime` | Realtime voice (OpenAI Realtime protocol, bidirectional audio over WebSocket) |

## Extras

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

## 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**
- **Own the ideas**
- **Own the inference path**
- **Minimize configuration**
- **Avoid vendor lock-in**
- **Use the smallest capable model**
- **Adapt to available hardware**
- **Keep the system understandable**
- **Prefer tailored agents over monolithic bloat**
- **Treat inference as infrastructure, not magic**
- **Cancel scopes you can reason about** — abort one session and only that session (plus its subagents) dies; abort the gateway and everything dies. No mystery middle ground.

## Design philosophy

rtxclaw follows a simple philosophy: small enough to understand, flexible enough to adapt, powerful enough to matter.

Customization should come from code and agent behavior, not from endless configuration sprawl. The system should adapt to the user, the hardware, and the workload, not force the user to adapt to the limitations of a vendor's pricing model or infrastructure bottlenecks.

This means:

- no blind dependence on one model provider
- no assumption that every task deserves frontier-model pricing
- no assumption that cloud is always the answer
- no assumption that local hardware is too weak to matter
- no assumption that one agent shape fits every machine

## Hardware-aware agents

rtxclaw is built around the idea that different hardware should produce different agent strategies.

A small local card like an RTX 3060 should not be treated the same way as a 4090, a 5090, an RTX A6000, or a high-memory neocloud GPU. The system should understand the available VRAM, throughput, latency, and cost envelope, then spawn the right kind of agent for the job.

Examples:

- **RTX 3060 / 4060-class**: lightweight routing, summarization, background memory work, small local copilots
- **RTX 3090 / 4090-class**: stronger coding agents, research agents, orchestration, hybrid local inference
- **RTX 5090-class**: high-end desktop inference, multi-agent local workflows, stronger reasoning on-prem
- **A6000 / workstation-class**: larger-context agents, heavier pipelines, persistent business-critical agent roles
- **Vast.ai / neocloud GPUs**: burst capacity, specialized heavy jobs, temporary swarms, overflow compute

The point is not to chase the biggest GPU.
The point is to make every GPU useful.

## What rtxclaw does

rtxclaw creates a custom-built agent system that:

- detects or knows the available inference capacity
- matches tasks to the right runtime and hardware tier
- spawns agents in seconds
- routes work based on cost, latency, and model capability
- reduces unnecessary API dependence
- uses neocloud only when it makes economic or operational sense
- preserves the option of on-prem inference as a first-class path
- keeps the architecture understandable enough to modify

## What makes it cypherpunk

Cypherpunk systems assume the network is hostile, dependency is dangerous, and convenience without control becomes a trap.

rtxclaw applies that logic to inference.

- If your intelligence depends entirely on remote providers, you do not control your intelligence.
- If your private reasoning is continuously exported, you do not control your ideas.
- If your costs can be repriced overnight, you do not control your operating margin.
- If your access can be revoked by policy, demand spikes, or product decisions, you do not control your future.

Sovereign inference means keeping optionality.
Sovereign inference means designing for adversarial conditions.
Sovereign inference means your agent system can still function when cloud prices spike, access tightens, models get rate-limited, or supply chains crack.

## Why now

As models get smarter and smaller, like Gemma 4 and Qwen3.5, the direction becomes obvious. The future belongs to systems that can run intelligence anywhere, on hardware you control, on hardware you rent intelligently, or on whatever inference capacity is available at that moment.

Model progress is shrinking the moat of centralized inference. Better small models plus better open-weight ecosystems mean the balance shifts toward adaptive systems that can move fluidly between local, workstation, datacenter, and burst cloud environments.

That is the world rtxclaw is built for.

## Architecture

The canonical architecture is documented in full in [`specs/rtxclaw.md`](specs/rtxclaw.md). Here is the high-level structure:

### Single-process agent gateway

```
                rtxclaw gateway (single parent process)
                ├─ binds 1 ACP HTTP listener (default :8100)
                ├─ child manager: lazy-spawn, idle-timeout, crash-respawn
                └─ /acp/<agent_name>/...  →  child stdio
                                              │
                ┌─────────────────────────────┼─────────────────────────────┐
                ▼                             ▼                             ▼
            main child                  scraper child         …      agent N child
        (rtxclaw agent acp-stdio,    (rtxclaw agent acp-stdio,   (per-agent process,
         CoreBackend(main))            CoreBackend(scraper))      lazy-spawned on first
                                                                  session/new for that name)
```

- **ACP-compliant.** The gateway is itself an ACP server. Each child is an ACP server over stdio. The gateway is a per-session multiplexing proxy.
- **Lazy spawn.** Children come up on first `session/new`; idle-timeout (default 30 min) reaps them. Bounded concurrency (default 16 live children).
- **Cancel cascade.** Gateway-level abort fans out to every live child. Per-session ACP cancel kills the parent's turn AND any subagent sessions it spawned.

### Abort & cancel scopes

**Narrow: `session/cancel` (per-session ACP cancel).** Cancels the in-flight turn on one session, including every subagent session that turn spawned. Other sessions stay running.

**Broad: `rtxclaw gateway stop` (SIGTERM the gateway).** Kills every session on every agent. Use when something is genuinely wedged.

Each child agent runs in its own process group (`start_new_session=True`). A wedged child cannot block gateway shutdown — SIGTERM escalates to SIGKILL after a grace period.

### Subagent infrastructure (canonical `Agent` tool)

The model spawns subagents via a single `Agent` tool:

```python
Agent(
  subagent_type="general-purpose" | "claude" | "codex" | "gemini",
  description="<label>",
  prompt="<task>",
  name="<sibling agent name>",
  model="<optional model override>",
  cwd="<optional cwd>",
)
```

| `subagent_type` | Routed to |
|---|---|
| `general-purpose` (or any sibling agent name) | sibling rtxclaw agent |
| `claude` | `claude -p` CLI bridge |
| `codex` | `codex` CLI bridge |
| `gemini` | `@google/gemini-cli` |

**Parallel fan-out.** Multiple `Agent` tool_use blocks in one response fan out via `asyncio.gather` across one subprocess per call.

### Monitor tool

Long-running background process registry. Four tools:
- `monitor_start(command, cwd?)` — spawn in its own process group
- `monitor_read(monitor_id, max_lines, timeout_s)` — pop unread lines
- `monitor_stop(monitor_id)` — SIGTERM → SIGKILL after grace period
- `monitor_list()` — every live monitor + buffer state

Plus a TUI `/monitors` panel for interactive management.

### Realtime Voice

Bidirectional audio streaming following the **OpenAI Realtime API event subset** over WebSocket. Server-side cascade: VAD → ASR → LLM → TTS, configurable per-stage (local, OpenAI, or any OpenAI-compatible endpoint).

```bash
python -m rtxclaw_realtime          # default 127.0.0.1:8123
python -m rtxclaw_realtime --port 8123 --host 0.0.0.0
```

Features: server VAD, barge-in, thinking-off mode (latency), base64 PCM16 24 kHz audio. Full spec at [`specs/realtime-voice.md`](specs/realtime-voice.md).

### Browser frontend

`rtxclaw_web` serves a browser-based chat UI that attaches to the agent gateway over WebSocket/SSE. Flask app with dashboard-authenticated access.

```bash
rtxclaw web start                    # default localhost:5000
pip install rtxclaw[web] && rtxclaw-web
```

### Logging & telemetry

Every tool call appends a structured event line to `<RTXCLAW_AGENT_HOME>/logs/gateway.log`. Greppable by event prefix (`MONITOR_START`, `DELEGATE_AGENT_START`, etc.). Best-effort writes — a rolled-away logfile never breaks the tool call.

### Session store

Per-session JSONL event log at `~/.rtxclaw/agents/<name>/sessions/<hash>.jsonl`. Unified `sessions.db` indexes every session across agents (state, model, title, parent session lineage). The log is the canonical source of truth and is written independent of any interface — every interface (TUI, Web, Telegram) tails the same durable log.

## The vision

rtxclaw is not a neocloud wrapper.
rtxclaw is not a dependency engine.
rtxclaw is not permissioned intelligence.

rtxclaw is sovereign inference infrastructure for the agent era.

It is a system where:

- your data stays under your control
- your agents adapt to your hardware reality
- your costs are shaped by intelligent routing, not vendor extraction
- your stack remains understandable enough to audit and modify
- your business does not collapse because someone else throttled access to intelligence

The AI future will not belong only to the largest labs.
It will belong to those who can route, compress, adapt, and deploy intelligence with discipline.

rtxclaw is built for that future.
