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