octorus

日本語

A TUI tool for GitHub PR review with Vim-style keybindings.

Features

• Browse changed files in a PR
• Split view with file list and diff preview side by side
• View diffs with syntax highlighting
• Add inline comments on specific lines
• Add code suggestions
• View and navigate review comments with jump-to-line
• Submit reviews (Approve / Request Changes / Comment)
• Fast startup with intelligent caching
• Configurable keybindings and editor
• AI Rally: Automated PR review and fix cycle using AI agents

Requirements

• GitHub CLI (gh) - Must be installed and authenticated
• Rust 1.70+ (for building from source)
• For AI Rally feature (optional, choose one or both):
  • Claude Code - Anthropic's CLI tool
  • OpenAI Codex CLI - OpenAI's CLI tool

Installation

cargo install octorus

Or build from source:

git clone https://github.com/ushironoko/octorus.git
cd octorus
cargo build --release
cp target/release/or ~/.local/bin/

Usage

# 1. Initialize config (recommended for AI Rally)
or init

# 2. Open PR list for current repository (auto-detected from git remote)
or

# 3. Open specific PR
or --repo owner/repo --pr 123

# 4. Start AI Rally (select PR from list, then auto-start)
or --ai-rally

Options

Initialize Configuration

Create default config files and prompt templates:

or init          # Create config files (skip if exists)
or init --force  # Overwrite existing files

This creates:

• ~/.config/octorus/config.toml - Main configuration file
• ~/.config/octorus/prompts/ - Prompt template directory
  • reviewer.md - Reviewer agent prompt template
  • reviewee.md - Reviewee agent prompt template
  • rereview.md - Re-review prompt template

Keybindings

File List View

Split View

The split view shows the file list (left, 35%) and a diff preview (right, 65%). The focused pane is highlighted with a yellow border.

File List Focus:

Diff Focus:

Diff View

Note: Lines with existing comments are marked with ●. When you select a commented line, the comment content is displayed in a panel below the diff.

Comment Panel (when focused):

Input Mode (Comment/Suggestion/Reply)

When adding a comment, suggestion, or reply, you enter the built-in text input mode:

Multi-line input is supported. Press Enter to insert a newline.

Comment List View

Configuration

Run or init to create default config files, or create ~/.config/octorus/config.toml manually:

# Editor to use for writing review body (Approve/Request Changes/Comment)
editor = "vi"

[diff]
# Syntax highlighting theme for diff view
theme = "base16-ocean.dark"

[keybindings]
# See "Configurable Keybindings" section below for all options
approve = "a"
request_changes = "r"
comment = "c"
suggestion = "s"

[ai]
# AI agent to use for reviewer/reviewee
# Supported: "claude" (Claude Code), "codex" (OpenAI Codex CLI)
reviewer = "claude"
reviewee = "claude"

# Maximum iterations before stopping
max_iterations = 10

# Timeout per agent execution (seconds)
timeout_secs = 600

# Custom prompt directory (default: ~/.config/octorus/prompts/)
# prompt_dir = "/custom/path/to/prompts"

# Additional tools for reviewer (Claude only)
# Use Claude Code's --allowedTools format
# reviewer_additional_tools = []

# Additional tools for reviewee (Claude only)
# Examples: "Skill", "WebFetch", "WebSearch", "Bash(git push:*)"
# reviewee_additional_tools = ["Skill", "Bash(git push:*)"]

Configurable Keybindings

All keybindings can be customized in the [keybindings] section. Three formats are supported:

[keybindings]
# Simple key
move_down = "j"

# Key with modifiers
page_down = { key = "d", ctrl = true }

# Two-key sequence
go_to_definition = ["g", "d"]

Available Keybindings

Note: Arrow keys (↑/↓/←/→) always work as alternatives to Vim-style keys and cannot be remapped.

Customizing Prompt Templates

AI Rally uses customizable prompt templates. Run or init to generate default templates, then edit them as needed:

~/.config/octorus/prompts/
├── reviewer.md    # Prompt for the reviewer agent
├── reviewee.md    # Prompt for the reviewee agent
└── rereview.md    # Prompt for re-review iterations

Templates support variable substitution with {{variable}} syntax:

AI Rally

AI Rally is an automated PR review and fix cycle that uses two AI agents:

• Reviewer: Analyzes the PR diff and provides review feedback
• Reviewee: Fixes issues based on the review feedback and commits changes

How it works

┌─────────────────┐
│  Start Rally    │  Press 'A' in File List View
└────────┬────────┘
         ▼
┌─────────────────┐
│    Reviewer     │  AI reviews the PR diff
│ (Claude/Codex)  │  → Posts review comments to PR
└────────┬────────┘
         │
    ┌────┴────┐
    │ Approve?│
    └────┬────┘
     No  │  Yes ──→ Done ✓
         ▼
┌─────────────────┐
│    Reviewee     │  AI fixes issues
│ (Claude/Codex)  │  → Commits locally (no push by default)
└────────┬────────┘
         │
    ┌────┴──────────────┐
    │                   │
    ▼                   ▼
 Completed    NeedsClarification /
    │          NeedsPermission
    │                   │
    │          User responds (y/n)
    │                   │
    └─────────┬─────────┘
              ▼
┌───────────────────────┐
│  Re-review (Reviewer) │  Updated diff:
│                       │  git diff (local) or
│                       │  gh pr diff (if pushed)
└───────────┬───────────┘
            │
       ┌────┴────┐
       │ Approve?│  ... repeat until approved
       └─────────┘       or max iterations

Features

• PR Integration: Review comments are automatically posted to the PR
• External Bot Support: Collects feedback from Copilot, CodeRabbit, and other bots
• Safe Operations: Dangerous git operations (--force, reset --hard) are prohibited
• Session Persistence: Rally state is saved locally and can be resumed
• Interactive Flow: When the AI agent needs clarification or permission, you can respond interactively
• Local Diff Support: Re-review iterations prioritize local git diff for unpushed changes; falls back to gh pr diff when changes have been pushed
• Background Execution: Press b to run rally in background while continuing to browse files

Recommended Configuration

Codex uses sandbox mode and cannot control tool permissions at a fine-grained level. For maximum security, we recommend:

Example configuration for secure setup:

[ai]
reviewer = "codex"   # Safe: read-only sandbox
reviewee = "claude"  # Recommended: fine-grained tool control
reviewee_additional_tools = ["Skill"]  # Add only what you need

Note: If you use Codex as reviewee, it runs in --full-auto mode with workspace write access and no tool restrictions.

Tool Permissions

Default Allowed Tools

Reviewer (read-only operations):

Reviewee (code modification):

Additional Tools (Claude only)

Additional tools can be enabled via config using Claude Code's --allowedTools format:

[ai]
reviewee_additional_tools = ["Skill", "Bash(git push:*)"]

Breaking Change (v0.2.0): git push is now disabled by default. To enable, add "Bash(git push:*)" to reviewee_additional_tools.

Keybindings (AI Rally View)

License

MIT