# R

Author: retoor <retoor@molodetz.nl>

R is a command-line AI assistant written in C that provides an autonomous agent with full system access through function calling. It interfaces with OpenAI-compatible APIs and operates in an agentic loop, reasoning about tasks, executing tools, and iterating until goals are achieved.

## Features

### Autonomous Agent Architecture
- ReAct (Reasoning + Acting) pattern implementation
- Automatic tool execution loop with up to 300 iterations
- Intelligent response parsing to detect incomplete work
- Automatic continuation when tasks require multiple steps
- Built-in retry logic for API failures

### AI Provider Support
- OpenAI API (default)
- Anthropic Claude
- Ollama (self-hosted)
- Grok
- Any OpenAI-compatible API endpoint

### Tool System
The agent has access to 15+ tools exposed via JSON schema descriptions:

| Tool | Description |
|------|-------------|
| `linux_terminal_execute` | Execute shell commands with output capture |
| `linux_terminal_execute_interactive` | Execute interactive commands (vim, htop, etc.) |
| `read_file` | Read file contents |
| `write_file` | Write content to files with automatic parent directory creation |
| `directory_glob` | List directory contents with file metadata |
| `mkdir` | Create directories recursively |
| `chdir` | Change working directory |
| `getpwd` | Get current working directory |
| `http_fetch` | Fetch URL contents via HTTP GET |
| `web_search` | Search the web for information |
| `web_search_news` | Search for news articles |
| `db_set` | Store key-value pairs in local SQLite database |
| `db_get` | Retrieve values from database |
| `db_query` | Execute arbitrary SQL queries |
| `index_source_directory` | Index source files with contents |
| `python_execute` | Execute Python code and capture output |

### Database
- Local SQLite database at `~/.r.db`
- Persistent key-value storage
- Full SQL query support
- File version history tracking

### REPL Interface
- Readline integration with tab completion
- Persistent command history at `~/.r_history`
- Markdown syntax highlighting in terminal output
- Session management for separate conversation contexts

### REPL Commands
| Command | Description |
|---------|-------------|
| `!dump` | Show raw message JSON |
| `!clear` | Clear conversation history |
| `!session` | Display current session info |
| `!verbose` | Toggle verbose mode |
| `!tools` | List available tools |
| `!models` | Show available models |
| `!model <name>` | Switch AI model |
| `exit` | Exit the REPL |

## Installation

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

On Debian/Ubuntu:
```bash
apt install libcurl4-openssl-dev libjson-c-dev libreadline-dev libncurses-dev libsqlite3-dev libgnutls28-dev libgmp-dev libssl-dev
```

### Build
```bash
make build
```

The binary is output to `bin/r` and copied to `./r`.

### Cross-Compilation
```bash
make build_mingw    # Windows executable
```

### AppImage
```bash
make appimage       # Creates portable r-x86_64.AppImage
```

## Configuration

### Environment Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `R_KEY` | API key (takes precedence over OPENAI_API_KEY) | `sk-...` |
| `OPENAI_API_KEY` | OpenAI API key (fallback) | `sk-...` |
| `OPENROUTER_API_KEY` | OpenRouter API key | `sk-or-...` |
| `R_BASE_URL` | Custom API base URL (without /v1/...) | `https://openrouter.ai/api` |
| `R_MODEL` | AI model name | `gpt-4o`, `x-ai/grok-code-fast-1` |
| `R_USE_TOOLS` | Enable/disable function calling | `true`, `false`, `1`, `0` |
| `R_USE_STRICT` | Enable strict mode for tool schemas | `true`, `false`, `1`, `0` |
| `R_SYSTEM_MESSAGE` | Custom system prompt injected at startup | Any text |
| `R_SESSION` | Default session name for conversation persistence | `myproject`, `$(date)` |

### Context Files
- `.rcontext.txt` - Project-specific context (current directory)
- `~/.rcontext.txt` - Global user context

## Bash Integration

Integrate R as a fallback command handler in bash. When a command is not found, R will attempt to interpret it as a natural language query with automatic date-based sessions.

Add to `~/.bashrc`:

```bash
export R_BASE_URL="https://openrouter.ai/api"
export R_KEY="$OPENROUTER_API_KEY"
export R_MODEL="x-ai/grok-code-fast-1"
export R_SESSION=$(date +%Y-%m-%d)

command_not_found_handle() {
    script_path="/path/to/r"
    first_argument="$1"
    if "$script_path" "$@"; then
        echo -e ""
    else
        echo "bash: $first_argument: command not found"
    fi
}
```

This enables:
- Automatic session per day via `R_SESSION=$(date +%Y-%m-%d)`
- Natural language commands directly in terminal
- Fallback to standard "command not found" on failure

## Why Terminal AI

Having an AI agent directly in your terminal eliminates context switching. Instead of copying error messages to a browser, describing your environment, or explaining file contents, the agent can see and act on everything directly.

### Practical Examples

**Debug errors instantly**
```bash
./r "The build failed, check the error and fix it"
# Agent reads error output, identifies the issue, edits the file, rebuilds
```

**Explore unfamiliar codebases**
```bash
./r "How does authentication work in this project?"
# Agent searches files, reads relevant code, explains the flow
```

**Automate repetitive tasks**
```bash
./r "Rename all .jpeg files to .jpg and create a backup folder first"
# Agent creates directory, moves files with proper naming
```

**System administration**
```bash
./r "Check disk usage and find the largest files in /var/log"
# Agent runs du, finds large files, presents a summary
```

**Database operations**
```bash
./r "Show me all users who signed up last week"
# Agent queries the database, formats results
```

**Web research while coding**
```bash
./r "What's the correct syntax for a PostgreSQL upsert?"
# Agent searches the web, returns the answer with examples
```

**Code generation**
```bash
./r "Write a Python script that monitors CPU usage and alerts if above 90%"
# Agent writes the script, saves it, makes it executable
```

**Git workflows**
```bash
./r "Show what changed since yesterday and summarize the commits"
# Agent runs git log, git diff, provides summary
```

**File operations**
```bash
./r "Find all TODO comments in this project and list them by file"
# Agent greps through codebase, organizes findings
```

**Data processing**
```bash
cat data.csv | ./r --stdin "Calculate the average of the third column"
# Agent processes piped data, returns calculation
```

**Multi-step tasks**
```bash
./r "Set up a new Python virtualenv, install requests and pytest, create a basic test file"
# Agent executes multiple commands in sequence, creates files
```

**Environment inspection**
```bash
./r "What ports are in use and what processes are using them?"
# Agent runs netstat/lsof, explains the output
```

The agent maintains conversation context within sessions, so follow-up queries understand previous actions. Combined with the bash integration, any unrecognized command becomes a natural language query to the AI.

## Usage

### Interactive Mode
```bash
./r
```

### Single Query
```bash
./r "What files are in the current directory?"
```

### With Piped Input
```bash
cat error.log | ./r --stdin "Analyze these errors"
```

### With Context File
```bash
./r --context project_docs.txt "Explain this project"
```

### Session Management
```bash
./r --session=myproject       # Named session
./r -s myproject              # Short form
```

### Options
| Flag | Description |
|------|-------------|
| `--verbose` | Enable verbose output |
| `--stdin` | Read prompt from stdin |
| `--context <file>` | Include file as context |
| `--py <file>` | Include Python file |
| `--session <name>` | Use named session |
| `--nh` | Disable syntax highlighting |
| `--free` | Use free tier API |
| `--api` | API mode |

## Architecture

### Header-Only Design
The codebase uses a header-only architecture where `.h` files contain both declarations and implementations. All code compiles through includes from `main.c`.

### Core Components
| File | Purpose |
|------|---------|
| `main.c` | Entry point, REPL loop, argument parsing |
| `agent.h` | Autonomous agent loop with ReAct pattern |
| `r.h` | Global configuration and environment handling |
| `auth.h` | API key resolution |
| `openai.h` | API communication |
| `chat.h` | JSON prompt construction |
| `messages.h` | Conversation history management |
| `tools.h` | Tool definitions and execution dispatcher |
| `http_curl.h` | libcurl wrapper for HTTP requests |
| `line.h` | Readline integration |
| `db_utils.h` | SQLite operations |
| `browse.h` | Web search functionality |
| `markdown.h` | Terminal markdown rendering |
| `utils.h` | Path utilities |
| `indexer.h` | Source directory indexing |

## License

MIT