orangu

orangu is a local workspace-aware tool-driven coding environment for OpenAI-compatible servers - especially llama.cpp.

orangu does not require an Internet connection after llama.cpp and models have been downloaded.

orangu is named after the Orangutan - the smartest ape.

Table of Contents

• Features
• Installation
  • Install dependencies on Fedora
  • Release build
  • Debug build
• Configuration and first run
• Documentation
• Tested platforms
• Contributing
• Community
• License

Features

• OpenAI-compatible chat completions, with special attention to llama.cpp workflows
• Workspace-aware local tools for reading, editing, listing, fetching, and shell commands
• Persistent terminal UI with workspace, server, and model status in the header, refreshed every minute while idle
• Shell-style prompt editing, history, scrolling, and context-sensitive Tab completion
• Local commands such as /help, /list_models, /list_files, /show_file, /tools, /diff, /status, /log, /pull, /rebase, /merge, /checkout, /add_file, /remove_file, /move_file, /cherry_pick, /commit, /amend, /push, /init_repo, /squash, /delete, and /open_file
• Natural-language local aliases such as open README.md, list models, list files, pull 58, log, status, rebase, merge feature/foo, checkout main, add README.md, remove README.md, move old.rs new.rs, cherry pick abc1234, commit "[#42] My feature", amend "[#42] My feature", push, force push, init repo, squash, delete feature/foo, and show help
• Streaming responses with live footer status such as Thinking (...) and llama.cpp-native Working @ X.Y t/s (...)
• Queued local commands while a response is in flight, plus double-Esc request cancellation
• Markdown rendering in the console, including bold, italic, headings, lists, links, and code
• Syntax highlighting for fenced code blocks in supported programming languages

Installation

Install dependencies on Fedora

Install the tools needed to build and run orangu from source:

dnf install -y git rust cargo gcc

Release build

The following commands build an optimized release binary:

git clone https://github.com/mnemosyne-systems/orangu.git
cd orangu
cargo build --release

The binary will be available at:

target/release/orangu

To install it system-wide:

sudo install -Dm755 target/release/orangu /usr/local/bin/orangu

Debug build

The following commands build a debug binary:

git clone https://github.com/mnemosyne-systems/orangu.git
cd orangu
cargo build

The binary will be available at:

target/debug/orangu

Configuration and first run

Start from the sample configuration:

cp doc/etc/orangu.conf ./orangu.conf

Default configuration lookup order:

1. ./orangu.conf
2. ~/.orangu/orangu.conf

Run the client:

orangu --config ./orangu.conf

Or run it directly from the build tree:

./target/release/orangu --config ./orangu.conf

By default, local tools operate on the current working directory. Use --workspace /path/to/project to point orangu at another tree.

Useful first commands:

/help
/list_models
/list_files
/show_file README.md
/tools
/status
/log
/cherry_pick abc1234
/commit "[#42] My feature"
/amend "[#42] My feature"
/squash
/delete feature/foo
/open_file README.md

Documentation

• Latest manual
• Getting Started
• Quick start
• Configuration
• Terminal interface
• Tools

Tested platforms

• Fedora 44

Contributing

Contributions to orangu are managed on GitHub:

• Ask a question
• Raise an issue
• Feature request
• Code submission

Contributions are most welcome.

Please consult the Code of Conduct before contributing.

Community

• GitHub: mnemosyne-systems/orangu
• Discussions: GitHub Discussions

License

GNU General Public License v3.0