Terminal Interface

orangu is an interactive terminal client with a persistent header and a prompt area anchored to the bottom of the terminal. This chapter covers the terminal itself: startup, the header and prompt, sessions, input editing, completion, and scrolling.

Startup#

When started inside a Git repository, orangu fast-forwards the local default branch (main/master) to origin so it is in sync with upstream. The sync runs in the background and never delays startup. Progress appears on the left of the status bar: Syncing with origin… while running, then Synced <branch> with origin for a few seconds. It is skipped silently when there is no origin remote.

Command-line options

Header#

The top banner displays: current version, workspace status, server status, model status, and a /help reminder. While no request is active, server and model status are rechecked once per minute.

Prompt area#

The prompt area stays at the bottom of the terminal window.

• Long input wraps upward
• Submitted input moves directly into the output area
• The banner and prompt stay fixed while the output window scrolls independently
• Markdown in assistant output is rendered with terminal styling: bold, italic, headings, lists, links, and code blocks with syntax highlighting when the language is supported

All slash commands are handled locally and are never sent to the model, so they continue to work even when the model is unavailable. Free-form prompts are blocked when the server or model status in the header is red.

Waiting state#

While the model is generating a response, the left side of the footer shows a rolling status indicator:

Thinking (2s)

You can keep typing and submitting commands while a response is pending. Submitted commands are queued and executed in order after the active response finishes.

The /pending command lists the queued commands, numbered in execution order; /pending delete <n> removes one by its number. The center of the footer mirrors the queue depth as Pending: X.

When using provider = llama.cpp, the footer switches from Thinking (<CLOCK>) to native generation throughput once tokens stream:

Working @ 42.5 t/s (2s)

Press Esc twice within 2 seconds during the waiting state to cancel the active request without exiting. Queued commands are preserved.

Sessions#

Each run creates or resumes a session identified by a UUID. Session data is stored under ~/.orangu/sessions/<uuid>/:

history    per-session command history (readline)
messages   full conversation turn history (JSON array)
metadata   session metadata (JSON)

The metadata file records when the session was created, last used, which workspace it belongs to, and which Git branch was active:

{
  "started_at": 1748000000,
  "last_updated_at": 1748003600,
  "workspace": "/home/user/myproject",
  "branch": "feature/my-pr"
}

Automatic resume

On startup, orangu checks whether a session already exists for the current workspace path and Git branch. If exactly one matching session with history is found, it is resumed automatically. The status bar shows:

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

If more than one session matches, a fresh session is started. Use --resume <uuid> to target a specific session explicitly.

Session cleanup on exit

On exit, the resume command is printed:

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

Sessions with no LLM interaction on main, master, or outside a Git repository are deleted automatically. Sessions on feature branches are always kept.

Natural-language command aliases#

Local commands can be entered in plain language, like open README.md, show status, create pull request, or switch model to <name>. The phrases recognized for each command are listed under its Examples in the Core tools, Git tools, and Usage tools chapters.

Comments and ignored input#

• First non-whitespace character #: treated as a local comment, shown in the transcript, not sent to the LLM
• First non-whitespace character \: the line is ignored entirely

Shortcuts and keys#

Prompt editing

History

History navigation preserves the current unfinished line as a draft and restores it when you move back out of history.

Inline command hints (ghost text)

As you type, a grey inline hint previews the command your input is growing into. It covers slash commands and natural-language bindings:

• Press Tab to accept the hint
• Press Shift+Tab to cycle through alternative candidates when several commands share the prefix
• The hint disappears once your input already spells a complete command
• Editing the line, moving the cursor, or pasting resets the cycle back to the first candidate

Waiting and exit control

Tab completion#

Tab uses context-sensitive completion. The first Tab inserts the first match; repeated presses cycle through remaining matches. Completion cycling resets as soon as you edit the line, move the cursor, or paste text.

The completion modes are checked in order:

1. /branch, /checkout, or checkout : complete branch names first, then workspace file paths
2. switch to : complete branch names and tag names
3. /add_file, add , add file : complete untracked directories first, then untracked files
4. /remove_file, remove , git rm : complete tracked directories first, then tracked files
5. /move_file: first argument from tracked files; second from all workspace paths
6. /cherry_pick, cherry pick : abbreviated commit hashes from the default branch
7. /merge, merge : local branch names first, then remote-only branch names
8. /branch -d, delete branch : local branch names excluding main/master
9. /session : session UUIDs sorted newest-first, then distinct workspace paths
10. /model : models available on the selected server
11. /server : names of all configured server sections
12. /open_file, /show_file: workspace file paths recursively; once a file is present, next Tab cycles commit history
13. /: built-in slash commands
14. Otherwise: filesystem entries from the current token relative to the workspace

Output scrolling and horizontal panning#

The output scrollback buffer keeps the most recent 10,000 lines. orangu maintains a virtual canvas wider than the visible terminal; source files shown with /show_file may contain lines longer than the terminal width, which are laid out on the full canvas and can be panned horizontally without reflowing. The virtual canvas width is set by the width key in the [orangu] config section (default 512).

Footer behavior#

• Left: Thinking (<CLOCK>) while waiting for a response to start; Working @ X.Y t/s (<CLOCK>) while tokens stream
• Center: Pending: X showing how many queued commands are waiting
• Right: the model name currently in use