Metadata-Version: 2.4
Name: oragent
Version: 0.3.2
Summary: Agent Supervisor for AI coding agents — a state-aware cockpit for managing multiple Claude Code, Codex, and Shell sessions in parallel.
Project-URL: Homepage, https://oragent.top
Project-URL: Repository, https://github.com/oragent-ai/oragent
Project-URL: Issues, https://github.com/oragent-ai/oragent/issues
Author: Phinease
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: jieba>=0.42
Requires-Dist: libtmux>=0.37.0
Requires-Dist: textual<8.2.0,>=8.1.1
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: textual-dev>=1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Oragent

[![PyPI](https://img.shields.io/pypi/v/oragent)](https://pypi.org/project/oragent/)
[![Python](https://img.shields.io/pypi/pyversions/oragent)](https://pypi.org/project/oragent/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![README EN](https://img.shields.io/badge/README-English-blue)](README.md)
[![README ZH](https://img.shields.io/badge/README-%E4%B8%AD%E6%96%87-red)](README.zh-CN.md)
[![README FR](https://img.shields.io/badge/README-Fran%C3%A7ais-green)](README.fr.md)

> **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.

<img width="1920" height="1050" alt="Oragent dashboard" src="https://github.com/user-attachments/assets/54896b30-3eff-4dbd-b9a4-f01cfaa150f8" />

## Languages

- [English](./README.md)
- [简体中文](./README.zh-CN.md)
- [Français](./README.fr.md)

## ✨ 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)

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

### Via pipx

```bash
pipx install oragent
```

### Via pip

```bash
pip install oragent
```

### Upgrade

```bash
pipx upgrade oragent
```

or:

```bash
pip install -U oragent
```

### Prerequisites

- Python >= 3.11
- tmux (`brew install tmux` / `apt install tmux`)

## ▶️ Usage

```bash
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

[MIT](LICENSE)
