Skip to content

README_FULL.md

Latest commit

 

History

History
321 lines (235 loc) · 8.38 KB

README_FULL.md

File metadata and controls

321 lines (235 loc) · 8.38 KB

Rust TUI Coder - Complete Documentation

A powerful terminal-based AI coding assistant that brings AI intelligence directly to your command line. Built with Rust for performance and reliability.

Table of Contents

  1. Overview
  2. Features
  3. Installation
  4. Configuration
  5. Usage
  6. Available Tools
  7. ReAct Pattern
  8. OS Compatibility
  9. Custom Prompts
  10. Examples
  11. Troubleshooting
  12. Contributing
  13. License

Overview

Rust TUI Coder is an intelligent terminal-based coding assistant that leverages large language models (LLMs) to help you with software development tasks. It features a beautiful terminal user interface built with Ratatui and provides real-time streaming responses.

Key Highlights

  • AI-Powered: Works with OpenAI, Anthropic, or local LLM providers
  • Beautiful TUI: Modern terminal interface with real-time updates
  • 27+ Tools: Comprehensive toolset for development tasks
  • ReAct Pattern: Intelligent reasoning before acting
  • Cross-Platform: Works on Linux, macOS, and Windows
  • Performance: Built with Rust for speed and reliability
  • Custom Prompts: Optional prompt.md for personalized instructions

Features

Core Features

  • Natural Language Interface: Communicate with the AI in plain English
  • Direct Tool Execution: AI can manipulate files and run commands
  • Real-time Monitoring: Watch tool execution happen live
  • Streaming Responses: See AI responses as they're generated
  • Session Tracking: Monitor tokens used, requests made, and tools executed
  • Planning System: Break down complex tasks into manageable steps

Advanced Features

  • ReAct Pattern: AI reasons through problems before taking action
  • OS Detection: Automatically adapts to Windows, Linux, or macOS
  • Time Awareness: Access to current date and time
  • Enhanced File Operations: Copy, move, and rename files easily
  • Custom System Prompts: Add your own instructions via prompt.md
  • Multi-Language Support: Execute code in Python, JavaScript, Rust, Go, Java, C/C++

Installation

From Crates.io

cargo install rust_tui_coder

From Source

git clone https://github.com/Ammar-Alnagar/Rust-Coder-CLI.git
cd Rust-Coder-CLI
cargo build --release
./target/release/rct

Configuration

Create a config.toml file in your working directory:

[llm]
provider = "openai"
api_key = "your-api-key-here"
api_base_url = "https://api.openai.com/v1"
model_name = "gpt-4"

# Optional: Automation settings
max_attempts = 12
workspace_root = ""
shell = "bash"
post_write_verify = true
safe_fs = true

Configuration Options

  • provider: LLM provider (openai, anthropic, or local)
  • api_key: Your API key for the provider
  • api_base_url: API endpoint URL
  • model_name: Model to use (or "AUTODETECT" for automatic detection)
  • max_attempts: Maximum tool execution attempts per task
  • workspace_root: Root directory for file operations (empty = current directory)
  • shell: Default shell to use (bash, sh, cmd, powershell)
  • post_write_verify: Verify file writes
  • safe_fs: Enable filesystem safety checks

Usage

Starting the Application

rct

Basic Commands

  • Type your request and press Enter to interact with the AI
  • /quit - Exit the application (shows usage summary)
  • /stats - Display current session statistics
  • UpDown - Scroll through conversation
  • PgUp/PgDn - Page up/down
  • Home/End - Jump to top/bottom

Example Interactions

You: Create a Python script that calculates fibonacci numbers and run it

AI: I'll create and execute the script...
[Creates fibonacci.py]
[Executes the script]
[Shows output: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34...]

Available Tools

Planning and Task Management

  1. CREATE_PLAN - Create a structured plan for complex tasks
  2. UPDATE_PLAN - Mark steps as completed
  3. CLEAR_PLAN - Remove plan when task is done

File Operations

  1. READ_FILE - Read file contents
  2. WRITE_FILE - Create or overwrite files
  3. APPEND_FILE - Add content to existing files
  4. SEARCH_REPLACE - Replace text in files
  5. DELETE_FILE - Remove files or directories

Enhanced File Operations

  1. COPY_FILE - Copy files
  2. MOVE_FILE - Move or relocate files
  3. RENAME_FILE - Rename files or directories

Directory Operations

  1. LIST_FILES - List directory contents
  2. LIST_FILES_RECURSIVE - Recursively list all files
  3. CREATE_DIRECTORY - Create directories

Search & Navigation

  1. GREP_SEARCH - Search for text patterns
  2. GLOB_SEARCH - Find files matching patterns

Code Execution

  1. EXECUTE_CODE - Execute code in multiple languages
  2. RUN_COMMAND - Execute shell commands

Development Workflow

  1. GIT_STATUS - Show git status
  2. GIT_DIFF - Show changes
  3. GIT_COMMIT - Commit changes
  4. GIT_LOG - View commit history

Quality Assurance

  1. RUN_LINT - Run code linters
  2. RUN_TESTS - Execute test suites

Package Management

  1. INSTALL_PACKAGE - Install packages

System Information

  1. GET_TIME - Get current date and time
  2. GET_OS_INFO - Get OS details and configuration

ReAct Pattern

The AI follows the ReAct (Reasoning + Acting) pattern for better decision-making:

How It Works

  1. REASON: AI thinks through what needs to be done
  2. ACT: Executes the appropriate tool
  3. OBSERVE: Analyzes results and decides next steps

Example

REASONING: I need to understand the project structure first.
ACTION: LIST_FILES in current directory
OBSERVATION: Found src/ directory with main.rs
REASONING: Now I'll read main.rs to understand the code
ACTION: READ_FILE src/main.rs

OS Compatibility

The assistant automatically detects your operating system and adapts:

OS Detection

  • Linux: Uses bash/sh, forward slashes, Unix commands
  • macOS: Similar to Linux with macOS-specific tools
  • Windows: Uses cmd.exe/PowerShell, backslashes, Windows commands

Check Your OS

You: What OS am I running?

AI: [Uses GET_OS_INFO tool]
Operating System Information:
• OS: Linux (Ubuntu 22.04)
• Architecture: x86_64
• Shell: bash / sh
• Path Separator: /

Custom Prompts

Create a prompt.md file in your working directory to add custom instructions:

# My Custom Instructions

## Code Style
- Always use meaningful variable names
- Add comments for complex logic
- Follow PEP 8 for Python code

## Project Preferences
- Use TypeScript over JavaScript
- Prefer functional programming patterns
- Write tests for all new features

## Communication Style
- Keep explanations concise
- Show code examples
- Explain your reasoning

The AI will automatically load and follow these instructions!

Examples

See EXAMPLES.md for 30+ detailed usage examples including:

  • File manipulation
  • Code generation and execution
  • Git workflows
  • Project setup
  • Testing and linting
  • Complex multi-step tasks

Troubleshooting

Common Issues

Config not found

# Create default config
rct
# Follow the prompts to create config.toml

API errors

  • Check your API key is correct
  • Verify the API endpoint URL
  • Ensure you have API credits/quota

Tool execution fails

  • Check file permissions
  • Verify required tools are installed (python3, node, git, etc.)
  • Check workspace_root setting

See TROUBLESHOOTING.md for more details.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development

# Clone the repository
git clone https://github.com/Ammar-Alnagar/Rust-Coder-CLI.git
cd Rust-Coder-CLI

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run

# Build release version
cargo build --release

License

Licensed under either of:

at your option.

Resources

**Built with using Rust **