RP: Professional CLI AI Assistant

Author: retoor retoor@molodetz.nl

RP is a sophisticated command-line AI assistant designed for autonomous task execution, advanced tool integration, and intelligent workflow management. Built with a focus on reliability, extensibility, and developer productivity.

Overview

RP provides autonomous execution capabilities by default, enabling complex multi-step tasks to run to completion without manual intervention. The assistant integrates seamlessly with modern development workflows through an extensive tool ecosystem and modular architecture.

Key Features

Core Capabilities

• Autonomous Execution: Tasks run to completion by default with intelligent decision-making
• Multi-Language Support: Automatic detection and analysis for Python, C, C++, Rust, Go, JavaScript, TypeScript, and Java
• Advanced Tool Integration: Comprehensive tool set for filesystem operations, web interactions, code execution, and system management
• Real-time Cost Tracking: Built-in usage monitoring and cost estimation for API calls
• Session Management: Save, load, and manage conversation sessions with persistent state
• Plugin Architecture: Extensible system for custom tools and integrations

Language-Agnostic Analysis

RP automatically detects the programming language and provides tailored analysis:

Language	Features
Python	Dependency detection, version requirements, breaking change detection (pydantic v2, FastAPI)
C/C++	Header analysis, stdlib/POSIX/external library detection, compiler flag suggestions, Makefile generation
Rust	Cargo.toml detection, crate analysis
Go	go.mod detection, package analysis
JavaScript/TypeScript	package.json detection, module analysis
Java	Maven/Gradle detection, dependency analysis

C/C++ Development Support

Full support for C and C++ projects including:

• Header Classification: Distinguishes between standard library, POSIX, local, and external library headers
• Compiler Flags: Automatic suggestion of -std=c99/c11/gnu99, -Wall, -Wextra, -pthread, -lm, etc.
• Library Detection: Maps headers to system packages (curl, openssl, sqlite3, zlib, ncurses, etc.)
• Package Manager Integration: Install commands for Debian/Ubuntu, Fedora, Arch, and Homebrew
• Build System Detection: Identifies Makefile, CMake, Meson, and Autotools projects
• Makefile Generation: Creates complete Makefiles with proper LDFLAGS and dependencies

Example: For code with #include <curl/curl.h>:

Language: c
Dependency: curl/curl.h → curl
Install: apt-get install -y libcurl4-openssl-dev
Linker: -lcurl

Developer Experience

• Visual Progress Indicators: Real-time feedback during long-running operations
• Markdown-Powered Responses: Rich formatting with syntax highlighting
• Sophisticated CLI: Color-coded output, command completion, and interactive controls
• Background Monitoring: Asynchronous session tracking and event handling

Advanced Features

• Workflow Engine: Orchestrate complex multi-step processes
• Agent Management: Create and coordinate specialized AI agents for collaborative tasks
• Memory System: Knowledge base, conversation memory, and graph-based relationships
• Caching Layer: API response and tool result caching for improved performance

Architecture

Modular Design

• core/: Core functionality including API integration, context management, and tool execution
• tools/: Comprehensive tool implementations for various operations
• agents/: Agent orchestration and management system
• workflows/: Workflow definition and execution engine
• memory/: Advanced memory management with knowledge storage and retrieval
• plugins/: Extensible plugin system for custom functionality
• ui/: User interface components and rendering
• autonomous/: Autonomous execution logic and decision-making
• cache/: Caching mechanisms for performance optimization

Data Storage

• Primary Database: SQLite backend for persistent data storage
• Knowledge Base: Markdown-based knowledge storage with semantic search
• Session Storage: Conversation history and state management
• Version Control: Integrated MiniGit for project state tracking

Tool Ecosystem

• Filesystem operations (read, write, search, patch)
• Web interactions (HTTP requests, search, scraping)
• Code execution (Python interpreter, shell commands)
• Database operations (key-value store, queries)
• Interactive controls (background sessions, process management)
• Memory operations (knowledge management, fact extraction)

Installation

Requirements

• Python 3.10+
• SQLite 3.x

Setup

pip install rp-assistant

Or from source:

git clone https://github.com/retoor/rp
cd rp
pip install -e .

Usage

Basic Commands

rp -i

rp "Create a Python script that fetches data from an API"

rp "Write a C program that uses libcurl to download a file"

rp --load-session my-session -i

rp --usage

Interactive Mode Commands

• /reset - Clear conversation history
• /verbose - Toggle verbose output
• /models - List available AI models
• /tools - Display available tools
• /usage - Show token usage statistics
• /cost - Display current session cost
• /budget - Set budget limits
• /shortcuts - Show keyboard shortcuts
• /save <name> - Save current session
• clear - Clear terminal screen
• cd <path> - Change directory
• exit, quit, q - Exit the assistant

Configuration

RP uses a hierarchical configuration system:

• Global config: ~/.prrc
• Local config: ./.prrc
• Environment variables for API keys and settings

Create default configuration:

rp --create-config

Design Decisions

Technology Choices

• Python 3.10-3.13: Leverages modern language features including enhanced type hints and performance improvements
• SQLite: Lightweight, reliable database for persistent storage without external dependencies
• OpenRouter API: Flexible AI model access with cost optimization and model selection
• Modular Architecture: Clean separation for maintainability and extensibility

Architecture Principles

• Modularity: Clean separation of concerns with logical component boundaries
• Extensibility: Plugin system and tool framework for easy customization
• Reliability: Comprehensive error handling, logging, and recovery mechanisms
• Performance: Caching layers, parallel execution, and resource optimization
• Language Agnostic: Support for multiple programming languages without bias

Tool Design

• Atomic Operations: Tools designed for reliability and composability
• Timeout Management: Configurable timeouts and retry logic
• Result Truncation: Intelligent handling of large outputs
• Parallel Execution: Concurrent tool execution for improved performance

Memory and Context Management

• Multi-layered Memory: Conversation history, knowledge base, and graph relationships
• Automatic Extraction: Fact extraction and relationship mapping
• Context Enhancement: Intelligent context building for improved AI responses
• Summarization: Conversation summarization for long-term memory efficiency

API Integration

RP integrates with OpenRouter for AI model access, supporting:

• Multiple model providers through unified API
• Cost tracking and optimization
• Model selection based on task requirements
• Streaming responses for real-time interaction

Extensibility

Plugin System

• Load custom tools and integrations
• Extend core functionality without modifying base code
• Plugin discovery and management

Workflow Engine

• Define complex multi-step processes
• Conditional execution and error handling
• Variable passing and result aggregation

Agent Framework

• Create specialized agents for specific domains
• Collaborative agent execution
• Task decomposition and delegation

Performance Considerations

Caching Strategy

• API response caching with TTL-based expiration
• Tool result caching for repeated operations
• Memory-efficient storage with compression

Resource Management

• Connection pooling for HTTP requests
• Background task management
• Memory monitoring and cleanup

Optimization Features

• Parallel tool execution
• Asynchronous operations
• Result streaming for large outputs

Security

• API key management through environment variables
• Input validation and sanitization
• Secure file operations with permission checks
• Path traversal prevention
• Sandbox security for command execution
• Audit logging for sensitive operations

Development

Running Tests

make test
pytest tests/ -v
pytest --cov=rp --cov-report=html

Code Quality

• Comprehensive test suite (545+ tests)
• Type hints throughout codebase
• Linting and formatting standards

Debugging

• Detailed logging with configurable levels
• Interactive debugging tools
• Performance profiling capabilities
• Error recovery and reporting

License

MIT License

Entry Points

• rp - Main assistant
• rpe - Editor mode
• rpi - Implode (bundle into single file)
• rpserver - Server mode
• rpcgi - CGI mode