// retoor retoor@molodetz.nl

R - Autonomous Terminal AI Agent

Project Overview

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.

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.

Architecture

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.
# Safe test execution
python3 agent_benchmark.py

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/.