r/README.md

// retoor <retoor@molodetz.nl>
# R

Author: retoor <retoor@molodetz.nl>

R is a high-performance command-line AI assistant written in C that provides a fully autonomous agent with unrestricted system access. It implements an advanced ReAct (Reasoning + Acting) loop, allowing it to perform complex, multi-turn tasks by executing tools, observing results, and refining its plan until the goal is achieved.

## Features

### 🚀 Autonomous Orchestration
- **Lead Orchestrator:** Implements a strict Plan-Execute-Verify-Conclude lifecycle.
- **Checklist Protocol:** Mandates visible progress tracking for complex projects.
- **Smart Scale Handling:** Automatically enforces proper directory structures for "huge" or multi-page projects.
- **Hierarchical Agents:** Spawns specialized sub-agents (researcher, developer, security) with managed orchestration budgets.

### ⚙️ Asynchronous Process Management
- **Universal Control:** Unified interface for backgrounding both Shell and Python tasks.
- **Real-Time Visibility:** Streams process output live to the terminal, automatically indented and prefixed with `[PID]`.
- **Granular Monitoring:** Capture exit statuses, poll logs, and terminate tasks using stable PID tracking.
- **Automatic Backgrounding:** Synchronous tasks that exceed timeouts are safely backgrounded without losing output.

### 🎨 Beautiful Terminal UI
- **Syntax Highlighting:** Professional Python source code previews with line numbers and ANSI coloring.
- **Markdown Rendering:** Full support for headers, lists, code blocks, and styling in agent responses.
- **PID Traceability:** Every line of process output is clearly labeled for easy debugging of concurrent tasks.

### 🛠️ Advanced Tool System
All tools are fully compliant with **OpenAI Strict Mode** and exposed via robust JSON schemas.

| Tool | Description |
|------|-------------|
| `linux_terminal_execute` | Execute shell commands with real-time output and PID tracking. |
| `python_execute` | Professional Python execution with syntax-highlighted previews. |
| `process_get_status` | **[Universal]** Monitor ANY background task, capture logs and exit codes. |
| `process_terminate` | **[Universal]** Safely shut down background processes and clean up logs. |
| `process_monitor` | System-wide process inspection with filtering and CPU sorting. |
| `write_file` / `read_file` | Atomic file I/O with automatic directory management. |
| `index_source_directory` | Deep indexing of codebases for architectural analysis. |
| `spawn_agent` | Orchestrate specialized workers for research, coding, or audits. |
| `web_search` / `http_fetch` | Integrated research and data gathering via Rexa API. |
| `db_query` / `db_set` | Persistent state and versioning via local SQLite database. |

### 🔒 Safety & Reliability
- **Sequence Integrity:** Context manager protects the "holy sequence" of messages during shrinking.
- **Atomic Verification:** Agent is forbidden from "lying" about actions; every file write is verified via tool output.
- **Crash Resilience:** Benchmark suite includes real-time persistent logging for deep debugging.

## Installation

### Dependencies
```bash
libcurl json-c readline ncurses sqlite3 gnutls gmp openssl
```

### Build & Install
```bash
make build
sudo make install
```

The binary is output to `bin/r`. Configuration is handled via environment variables (`R_KEY`, `R_MODEL`, `R_BASE_URL`) or local `.rcontext.txt` files.

## License
MIT