Rylo Coder

A local-first CLI agent for Arch Linux administration and code/file editing.

Rylo Coder connects Ollama, llama.cpp, OpenRouter, or another OpenAI-compatible chat backend to a controlled set of filesystem, SearXNG-backed web search, fetch, and shell tools. It keeps a compact conversation state, injects an Arch-focused system prompt, routes tool calls through a safety layer, and records audit events for command and path decisions.

---

✨ Features

• Local-First Design – Runs entirely on your machine with optional cloud backend support
• Arch Linux Optimized – Built-in pacman, systemctl, journalctl, and AUR helper awareness
• Safety-First – Three safety modes (approve, allowlist, yolo) with audit logging
• Multi-Backend Support – Ollama, llama.cpp, OpenRouter, and OpenAI-compatible APIs
• Persistent Sessions – Save and resume work with JSON session files
• Rich TUI – Color-coded terminal interface with structured message blocks
• 14 Built-in Tools – File operations, directory management, regex search, SearXNG web search, web fetch, and safe shell execution

---

🚀 Quick Start

Prerequisites

• Python 3.10+
• Arch Linux (or compatible distribution)
• Ollama, llama.cpp server, or OpenRouter API key

Installation

See the full Installation Guide for all methods.

# Clone the repository
git clone https://github.com/vidproject1/rylo-coder.git
cd rylo-coder

# Run the launcher (auto-creates venv and installs dependencies)
./rylo-coder

Or install system-wide:

# Create user-local launcher symlink
mkdir -p ~/.local/bin
ln -sf "$PWD/rylo-coder" ~/.local/bin/rylo-coder

# Run from anywhere
rylo-coder

---

📖 Usage

Basic Interaction

$ rylo-coder

[AGENT] Rylo Coder ready. How can I help?

> list files in the current directory

[TOOL] list_directory(path=".")
[OK] 13 entries found

[AGENT] Here are the files in your directory...

Slash Commands

Command	Description
/help	Show available CLI commands
/model	Show current model
/model <name>	Switch to a different model
/history	Show all configured or previously used models
/models	List available Ollama models
/open-r key <key> model <id>	Configure OpenRouter backend
/think	Toggle thinking mode
/steps <n>	Set a tool-loop step limit for this session
/steps unlimited	Remove the tool-loop step limit
/usage	Show context usage and stats
/save <name>	Save current session
/load <name>	Load a saved session
/clear	Clear current context
/exit, /quit	Exit the harness

Safety Modes

Configure in config/settings.yaml or via environment:

Mode	Behavior
approve	Every shell command requires approval
allowlist	Read-only commands auto-run; mutating commands require approval
yolo	Most actions allowed except hard-denied dangerous patterns

---

⚙️ Configuration

Default Settings

Edit config/settings.yaml:

model: "qwen3.5-9b-q4_K_M-llamacpp.gguf"
backend_url: "http://127.0.0.1:8085/v1/chat/completions"
context_window: 16384
context_threshold: 0.70
max_output_chars: 3000
command_timeout: 30
safety_mode: "allowlist"
temperature_chat: 0.7
temperature_tools: 0.0
tail_turns: 8
max_tool_steps: 0  # 0 means unlimited
thinking_enabled: false
workspace_root: "."
session_dir: "~/.local/share/rylo-coder/sessions"
audit_log: "progress/audit.log"

User Overrides

Place user-specific settings in ~/.config/rylo-coder/settings.yaml. This is where /open-r stores API keys without modifying the repo config.

Web Search Configuration

Web search uses SearXNG-compatible JSON endpoints first. With web_search_url: "auto", Rylo Coder tries a small list of public SearXNG instances, then falls back to basic free HTML search endpoints if SearXNG is unavailable. Set web_search_url to your own SearXNG /search endpoint for more reliable and private search.

web_search_enabled: true
web_search_url: "auto"
web_search_max_results: 5
web_fetch_max_chars: 12000
web_timeout: 12
web_search_allow_private_hosts: true
web_fetch_allow_private_hosts: false

---

🛠️ Available Tools

Rylo Coder exposes these structured tools to the model:

Tool	Description
list_directory	List directory entries
read_file	Read a text file with line limits
write_file	Create or overwrite a file
patch_file	Exact text replacement in existing file
append_file	Append text to a file
create_directory	Create directories
move_path	Move or rename files/directories
copy_path	Copy files/directories
delete_path	Delete files/directories (approval-required)
search_files	Regex search under a directory
web_search	Search the web with SearXNG first, then free HTML fallbacks
web_fetch	Extract readable text from URLs
system_info	Collect system information
run_bash	Execute shell commands through safety layer

---

📁 Project Structure

rylo-coder/
├── rylo-coder          # Main executable launcher
├── requirements.txt    # Python dependencies
├── README.md           # This file
├── LICENSE             # MIT License
├── .gitignore          # Git ignore rules
├── config/
│   ├── settings.yaml   # Default configuration
│   ├── tools.yaml      # Tool inventory
│   └── model_presets.json
├── src/
│   ├── agent.py        # CLI entry point, agent loop
│   ├── ollama.py       # Ollama/OpenAI HTTP client
│   ├── config.py       # Settings loader and validator
│   ├── context.py      # Message management, compaction
│   ├── prompt.py       # System prompt assembly
│   ├── tools.py        # Tool schemas and implementations
│   ├── safety.py       # Command/path safety policy
│   ├── ui.py           # Terminal rendering (rich)
│   └── ...             # Additional modules
├── docs/
│   ├── arch_cheatsheet.md      # Arch Linux reference
│   └── harness_tech_stack.md   # Technical documentation
├── tests/              # Unit tests
├── progress/           # Audit logs (git-ignored)
└── .venv/              # Virtual environment (git-ignored)

---

🔒 Safety

Hard-Denied Commands

The following patterns are always blocked:

• Pipe-to-shell installers (curl ... | sh)
• Fork bombs
• Filesystem formatting commands
• dd writes to block devices
• Power control (shutdown, reboot, poweroff, halt)
• Dangerous recursive deletion/chmod
• Hidden payloads via sh -c

Protected Paths

Writes to these paths require explicit approval:

/, /boot, /dev, /etc, /proc, /root, /sys, /usr, /var/lib/pacman

Audit Logging

All command and path safety decisions are logged to progress/audit.log as JSON lines.

---

🧪 Testing

# Run all tests
python -m unittest discover tests/

# Run with coverage
python -m coverage run -m unittest discover tests/
python -m coverage report

# Using Make
make test
make coverage

---

📄 License

MIT License – see LICENSE for details.

---

🤝 Contributing

Quick Start

# Fork and clone
git clone https://github.com/your-username/rylo-coder.git
cd rylo-coder

# Create virtual environment
make venv
make install

# Run tests
make test

# Create a branch
git checkout -b feature/amazing-feature

Full Process

1. Fork the repository
2. Create a branch (git checkout -b feature/amazing-feature)
3. Make your changes following the code style guidelines
4. Run tests (make test or python -m unittest discover tests/)
5. Commit with clear messages (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

---

📚 Documentation

Document	Description
README	This file - project overview
INSTALL	Installation guide
Examples	Usage examples and tutorials
Quick Start	5-minute getting started guide
FAQ	Frequently asked questions
Arch Cheatsheet	Quick reference for Arch Linux commands
Tech Stack	Detailed technical documentation
Roadmap	Development roadmap
Release	Release process
Contributing	How to contribute to the project
Code of Conduct	Community guidelines
Security	Security policy and best practices
Changelog	Version history
Support	How to get help

---

🙏 Acknowledgments

• Built with rich and prompt_toolkit
• Web search is powered primarily by SearXNG, a free metasearch engine licensed under the GNU AGPL-3.0. Rylo Coder does not vendor SearXNG source; if you run or modify your own SearXNG instance, follow SearXNG's license terms.
• Designed for Arch Linux users
• Inspired by local-first AI agent research