2026-01-29 08:06:31 +01:00
// retoor < retoor @ molodetz . nl >
2026-01-29 06:54:10 +01:00
# R - Autonomous Terminal AI Agent
## Project Overview
2026-01-29 08:06:31 +01:00
**R** is a high-performance, autonomous AI agent written in C. It leverages the ReAct pattern to navigate complex system-level tasks by iteratively executing native tools and analyzing their output. Designed for Lead Orchestration, it manages specialized workers and background processes with high precision.
2026-01-29 06:54:10 +01:00
2026-01-29 08:06:31 +01:00
### Key Capabilities
* **Asynchronous Engine:** Robust fork/exec mechanism with real-time log tailing and PID management.
* **Sequence-Aware Context:** Advanced management of conversation history that preserves the structural integrity of message pairs (Assistant/Tool) and system prompts.
* **Professional UI:** Integrated Markdown and code renderers providing syntax highlighting and indented process output for superior DX.
* **Benchmarking:** Python-based integration suite with real-time persistent logging for debugging complex agent logic.
2026-01-29 06:54:10 +01:00
## Architecture
2026-01-29 08:06:31 +01:00
The project has evolved from a header-only design to a modular, professional C structure with clear separation of concerns.
### Core Implementation (`src/`)
* ** `main.c` **: Orchestration logic, REPL loop, and Lead Orchestrator system prompt injection.
* ** `agent.c` **: Core agentic loop with support for sub-agent spawning and verbose LLM logging.
* ** `bash_executor.c` **: Advanced process control using non-blocking `waitpid` and log file monitoring.
* ** `context_manager.c` **: Holy-sequence-aware shrinking logic that maintains API compatibility during context overflows.
* ** `markdown.c` **: ANSI-based rendering engine for Markdown and Python syntax highlighting.
* ** `tools/` **: Universal process tools and specialized worker logic.
### Data & State
* **SQLite Persistence:** `~/.r.db` manages key-value state and file versioning.
* **Session History:** Managed via `src/messages.c` with support for loading/saving separate contexts.
* **Background Logs:** Persistent task output stored in `/tmp/r_process_<pid>.log` .
## Development & Testing
### Strict Mode Compliance
All tools follow strict JSON schema definitions:
* `additionalProperties: false`
* All properties explicitly listed in the `required` array.
* Type-safe return objects (exit codes, booleans, strings).
### Testing Protocol
The `agent_benchmark.py` script provides 20 detailed test cases covering:
1. **Parallel Execution:** Multiple Python/Shell tasks running async.
2. **Process Lifecycle:** Termination, exit code capture, and backgrounding.
3. **Complex Orchestration:** Web research handover to developers.
4. **System Maintenance:** Codebase indexing and header verification.
2026-01-29 06:54:10 +01:00
```bash
2026-01-29 08:06:31 +01:00
# Safe test execution
python3 agent_benchmark.py
2026-01-29 06:54:10 +01:00
```
2026-01-29 08:06:31 +01:00
## Conventions
* **Header Style:** Every file must begin with `// retoor <retoor@molodetz.nl>` .
* **Defensive C:** Strict buffer management, mandatory `malloc` checks, and `NULL` pointer safety.
* **Logging:** LLM requests and responses go to `stderr` in verbose mode for auditability.
* **Modularity:** Prioritize small, focused files and clear interface definitions in `include/` .
