Oragent

An Agent Supervisor for AI coding agents — a state-aware cockpit so you see which agent needs you, auto-handle routine permissions, and stay in flow.

Languages

• English
• 简体中文
• Français

✨ Features

• Built-in Claude Code / Codex / Shell session support
• In-dashboard permission handling
• Vim-style modal operation
• Working / Idle / Waiting / Stopped / Auto / Shell state display
• High-performance line-level rendered preview (TerminalView) with Strip caching
• Interactive cursor overlay in snapshot preview
• Raw-stdin interactive input path with Shift+Enter / Alt+Enter newline compatibility
• Preview cache and single-flight refresh to reduce repeated preview work
• Typing-aware smart refresh: suppresses preview updates during rapid input
• Preview truncation hint when pane history exceeds the current 1000-line preview window
• WAITING auto-focus with FIFO queue processing
• Per-session Auto Pilot
• Home page, session panel toggle, and smoother session deletion flow
• Read-only diagnostics for cursor stability and live-session latency profiling
• macOS notifications

🚀 Installation

Quick Install (recommended)

curl -fsSL https://raw.githubusercontent.com/oragent-ai/oragent/main/install.sh | sh

Via pipx

pipx install oragent

Via pip

pip install oragent

Upgrade

pipx upgrade oragent

or:

pip install -U oragent

Prerequisites

• Python >= 3.11
• tmux (brew install tmux / apt install tmux)

▶️ Usage

oragent

⌨️ Keybindings

Normal Mode

Key	Action
↑ / ↓	Navigate sessions
n	New session
r	Rename session
i	Enter Interactive mode
a / d	Approve / Deny permission request
1-9	Select numbered permission option
p	Toggle Auto Pilot
c	Select mode (text copy)
Ctrl+\	Toggle session panel
Ctrl+x	Delete session
q	Quit Oragent

Interactive Mode

All keystrokes pass through directly to the selected agent session.

Key	Action
Ctrl-]	Exit to Normal mode
Ctrl+\	Toggle session panel
Shift+Enter	Newline (kitty protocol terminals)
Alt+Enter	Newline (legacy terminals)
Mouse click on session list	Switch session

🪟 Preview Behavior

• Normal and interactive preview both keep a bounded 1000-line window.
• When older content is omitted from the preview window, Oragent shows a truncation banner below the preview.
• Waiting detection and Auto Pilot still use plain capture-pane, independent of preview truncation.

Environment variables:

• ORAGENT_PREVIEW_HISTORY_LINES Current implementation clamps this to at least 1000.
• ORAGENT_INTERACTIVE_PREVIEW_HISTORY_LINES Current implementation also clamps this to at least 1000.
• ORAGENT_USE_LEGACY_INTERACTIVE_VIEW=1 Disables the interactive cursor overlay path and falls back to the legacy interactive preview behavior.
• ORAGENT_OUTPUT_DEBOUNCE_MS Drain output debounce interval in ms (default 16, ≈60fps).
• ORAGENT_TYPING_SUPPRESS_MS During interactive mode, defer preview refreshes while the user is typing faster than this threshold (default 0, disabled). The historical default 80 was calibrated to a pre-optimisation ~80 ms capture cost; since the one-shot capture path (~6 ms) there is nothing to coalesce. Set to 80 to restore the legacy behaviour if needed.

Migrating from CCT? All CCT_* env vars are still recognized in v0.3.x with a deprecation warning, and will be removed in v0.4.0.

🧪 Diagnostics

• python tests/e2e_cursor_scope.py Verifies cursor position and mixed ASCII / Chinese input stability.
• python tests/e2e_latency_scope_existing_sessions.py Reuses current live tmux sessions in read-only mode to profile preview, list, and polling costs.
• python tests/e2e_interactive_latency.py Measures interactive mode latency: drain debounce, capture, parse, render, and end-to-end refresh cycle.

🖥️ Interface

+----------------------------------------------------------------+
| Oragent · Agent Supervisor                                     |
+----------------------------------------------------------------+
| Sessions           | Preview: frontend-refactor (claude)        |
|--------------------|---------------------------------------------|
| * frontend-refactor| > Analyzing src/components/Header.tsx...    |
|   proj/frontend    |                                             |
| * api-fix          |   I'll update the Header component to       |
|   proj/backend     |   use the new theme variables.              |
| ! test-fix         |---------------------------------------------|
|   proj/tests       | ! Permission: execute `npm test`            |
| o data-migration   |   [a:Allow] [d:Deny]                        |
|   proj/migration   |                                             |
+--------------------+---------------------------------------------+
| NORMAL — i:Interactive  n:New  a/d:Allow/Deny  p:Pilot         |
+----------------------------------------------------------------+

Status icons: * Working  ! Waiting  o Idle  x Stopped

📝 Notes

• The current interactive preview is still tmux snapshot based, not a full terminal-buffer renderer.
• v0.2.2 replaced RichLog with a line-level TerminalView (ScrollView + render_line), reducing preview render cost by ~61%. Combined with drain debounce reduction and typing-aware smart refresh, end-to-end interactive latency dropped from ~145ms to ~65ms.
• v0.2.5 fixed interactive cursor off-by-one offset caused by trailing newline in tmux capture-pane output. Session names now truncate with ellipsis instead of disappearing when the panel is narrow.

🛣️ Roadmap

Version	Goal	Status
v0.2 (as CCT)	Claude Code / Codex / Shell sessions, Auto Pilot, bounded preview, TerminalView performance, cursor fix, diagnostics	✅ released
v0.3 (Oragent)	Rename to Oragent, more tools (Aider/Open Claw), session groups, fuzzy search	🚧 current
v0.4	Web version, diff view, Docker isolation	📋 planned

📄 License

Oragent is free, closed-source software distributed under the Oragent Free Use License v1.0 — free for personal and commercial use; no redistribution, reverse engineering, or paid forks. See LICENSE for the full text.

This is not an OSI-approved open-source license. The source code, build scripts, and internal documents are not part of the distribution.