R - Autonomous Terminal AI Agent

Project Overview

R is a command-line autonomous AI agent written in C. It implements the ReAct (Reasoning + Acting) pattern to perform complex tasks by iteratively executing tools (shell, file I/O, web search, database) and analyzing their output.

Key Features

  • Agentic Loop: Autonomous reasoning and execution cycle (up to 300 iterations).
  • Multi-Provider: Supports OpenAI, Anthropic, Ollama, Grok, etc.
  • Tool Ecosystem: Native C implementations for file operations, system commands, HTTP requests, and SQLite storage.
  • Persistence: Local SQLite database (~/.r.db) and session history.
  • Shell Integration: Functions as a fallback handler for bash "command not found" errors.

Architecture

The project follows a standard C project structure with separated interface and implementation.

Directory Structure

  • src/: Core implementation files.
    • main.c: Entry point, REPL loop, and argument parsing.
    • agent.c: Core ReAct loop logic.
    • tools/: Individual tool implementations (e.g., tool_file.c, tool_http.c).
  • include/: Header files defining the public API for modules (e.g., agent.h, tool.h).
  • testit/: Python-based integration testing framework.
  • Makefile: Build configuration.

Data Storage

  • Database: ~/.r.db (SQLite) stores key-value pairs and other persistent data.
  • History: ~/.r_history stores REPL command history.
  • Context: .rcontext.txt (local) and ~/.rcontext.txt (global) provide persistent context to the agent.

Building and Running

Dependencies

Requires: libcurl, json-c, readline, ncurses, sqlite3, gnutls, gmp, openssl.

Debian/Ubuntu:

sudo apt install libcurl4-openssl-dev libjson-c-dev libreadline-dev libncurses-dev libsqlite3-dev libgnutls28-dev libgmp-dev libssl-dev

Build Commands

  • Build: make build (Outputs binary to bin/r and copies to ./r)
  • Clean: make clean
  • Install: make install (Installs to /usr/local/bin/r)

Usage

  • Interactive REPL: ./r
  • One-shot Command: ./r "Create a hello world file in python"
  • Piped Input: cat logs.txt | ./r --stdin "Analyze these logs"

Testing

The project uses a custom Python-based testing framework located in testit/.

WARNING: The test script (testit/test.py) performs aggressive directory cleanup. ALWAYS run tests in a dedicated, isolated directory (e.g., inside testit/test_dir/), never in the project root.

# Example safe test execution
cd testit/test_dir
python3 ../test.py

Development Conventions

  • Language: C (Standard C99/C11).
  • Style: snake_case for functions and variables.
  • Error Handling: Extensive use of return codes and error checking (see r_error.c).
  • Memory Management: Explicit malloc/free. Tools must manage their own memory.
  • Tool Definition: Tools are registered in src/tool_registry.c and implemented in src/tools/. New tools must return a JSON string output.

Configuration

Configuration is handled via environment variables and runtime flags:

  • R_KEY / OPENAI_API_KEY: API authentication.
  • R_MODEL: Target model (e.g., gpt-4, claude-3-opus).
  • R_SESSION: Session identifier for context continuity.