Quick Start

This chapter gets orangu running against a local OpenAI-compatible server such as llama.cpp with the sample configuration in doc/etc/orangu.conf.

Install orangu#

The quickest way to install the latest release binary is the one-liner installer.

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/mnemosyne-systems/orangu/main/install.sh | sh

Windows (Command Prompt):

curl -fsSL https://raw.githubusercontent.com/mnemosyne-systems/orangu/main/install.cmd -o install.cmd && install.cmd

Windows (PowerShell alternative):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/mnemosyne-systems/orangu/main/install.cmd -OutFile install.cmd; .\install.cmd

The script installs to ~/.local/bin (Linux/macOS) or %USERPROFILE%\.local\bin (Windows) and warns if the directory is not in your PATH. See Building for instructions on building from source.

Start llama.cpp#

Run llama-server with your preferred model:

llama-server -hf ggml-org/gemma-4-E4B-it-GGUF \
             --port 8100 \
             --ctx-size 65536 \
             -sm layer \
             -t 4 \
             --webui-mcp-proxy \
             --fit on

orangu expects an OpenAI-compatible endpoint:

http://localhost:8100/v1

Create a configuration#

The fastest path is the interactive wizard, which auto-detects a model from the server and writes ~/.orangu/orangu.conf:

orangu --init

See Configuration for details of the wizard. Or copy the sample:

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

Default configuration lookup order:

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

Run the client#

orangu

Or point it at a specific configuration file:

orangu --config ./orangu.conf

By default the workspace tools operate on the current directory. Use --workspace /path/to/project to point orangu at another tree. The startup flags have short forms: -c for --config, -w for --workspace, -r for --resume, and -i for --init.

First commands to try#

/help
/server
/disconnect
/reload
/tools
/model
/session <UUID>
/list_files
/open_file README.md
/show_file README.md
/build
/add_file README.md
/amend "[#42] My feature"
/branch main
/branch -b feature/new
/branch -m new-name
/branch -d feature/old
/cherry_pick abc1234
/comment 51 "My comment"
/close -i 51
/commit "[#42] My feature"
/restore README.md
/diff
/init_repo
/log
/log 5
/merge feature/foo
/move_file old.rs new.rs
/pull 42
/push
/push --force
/rebase
/remove_file README.md
/review
/squash
/status
/usage
/clear
/quit

Sessions#

orangu automatically resumes an existing session when you return to the same workspace and Git branch. When a previous session is found, the status bar shows:

Resuming session 550e8400-e29b-41d4-a716-446655440000

for five seconds or until the first command is run. On exit, the resume command is printed so you can return from a different branch or machine:

orangu --resume 550e8400-e29b-41d4-a716-446655440000

Sessions that had no LLM interaction on main, master, or outside a Git repository are deleted automatically on exit. Feature branch sessions are always kept.

Comments and ignored input#