Roura Agent

Local-first AI coding assistant with multi-provider support.

Roura Agent is a powerful terminal-based AI assistant for software development. It supports multiple LLM providers (Ollama, OpenAI, Anthropic) with native tool calling, giving you Claude Code-like capabilities with the flexibility to choose your provider.

Quick Start

# Install
pip install roura-agent

# Run with auto-detected provider
roura-agent

# Or specify a provider
OPENAI_API_KEY=xxx roura-agent
ANTHROPIC_API_KEY=xxx roura-agent
roura-agent --provider ollama

Features

Multi-Provider Support

Provider is auto-detected based on available credentials, or you can force one with --provider.

Agentic Loop

• Multi-turn execution - Works iteratively until your task is complete
• Native tool calling - Direct integration with modern LLMs
• Context-aware - Tracks files you've read and modified
• Session persistence - Auto-saves conversations, resume with /resume

45+ Development Tools

• File operations - Read, write, edit files with visual diff preview
• Git integration - Status, diff, log, add, commit
• Shell commands - Execute with safety guardrails
• Search - Glob patterns and grep across your codebase
• GitHub - List, view, and create PRs and issues
• Jira - Search, view, create, and transition issues

Safety & Control

• Approval gates - Review and approve changes before they happen
• Visual diffs - See exactly what will change
• Undo support - Restore previous file versions with /undo
• Read-before-modify - Files must be read before they can be edited
• Secrets detection - Blocks credential commits
• Blast radius limits - --allow and --block patterns
• Dry-run mode - Preview all changes with --dry-run
• Read-only mode - Block all modifications with --readonly

User Experience

• Rich TUI - Beautiful terminal interface with colors and formatting
• Streaming responses - See output as it's generated
• Progress indicators - Elapsed time display during operations
• Token tracking - Monitor context usage

Installation

From PyPI (Recommended)

pip install roura-agent

From Source

git clone https://github.com/roura-io/roura-agent.git
cd roura-agent
pip install -e .

Provider Setup

Option 1: Ollama (Local, Free)

# Install Ollama from ollama.com
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull qwen2.5-coder:32b

# Set environment
export OLLAMA_MODEL=qwen2.5-coder:32b

Option 2: OpenAI

export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o  # optional, defaults to gpt-4o

Option 3: Anthropic

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_MODEL=claude-sonnet-4-20250514  # optional

Usage

# Start in your project directory
cd /path/to/your/project
roura-agent

# Example interactions:
> Read the main entry point and explain what it does
> Fix the bug in the login function
> Add input validation to the user form
> Create a new API endpoint for user profiles

CLI Options

roura-agent [OPTIONS]

Options:
  -p, --provider TEXT    LLM provider: ollama, openai, anthropic
  -s, --safe-mode        Disable dangerous tools
  -n, --dry-run          Preview changes without writing
  -r, --readonly         Block all file modifications
  -a, --allow TEXT       Only allow modifications to matching globs
  -b, --block TEXT       Block modifications to matching globs
  -d, --debug            Enable debug logging

Interactive Commands

Subcommands

roura-agent doctor       # Run system health checks
roura-agent setup        # Interactive configuration wizard
roura-agent config       # Show current configuration
roura-agent tools        # List all tools with risk levels
roura-agent ping         # Test Ollama connectivity
roura-agent project      # Show project information

Configuration

Configuration is stored in ~/.config/roura-agent/:

roura-agent setup  # Interactive configuration wizard

Environment Variables

Comparison

Development

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Code Quality

ruff check roura_agent/
pyright roura_agent/

License

MIT License - See LICENSE for details.

Support

• Issues: GitHub Issues
• Documentation: docs.roura.io