日本語

View and review GitHub PR diffs and local diffs exceeding 6,000 files and 300,000 lines — right in your terminal. Two AI agents automatically review and iterate on corrections until approval.

Octorus is currently undergoing significant refactoring and feature additions for v6.0.0. Some features that have not yet been released are already reflected in the README. We will deliver them to you soon, so please wait a little longer.

• Fast startup with intelligent caching
• Tested with 6,000+ files and 300,000+ lines

Automated PR review and fix cycle using AI agents. A reviewer agent analyzes diffs and posts comments, then a reviewee agent fixes issues and commits — looping until approved.

Preview local git diff HEAD in real time with file watcher — no PR required. Toggle between PR mode and Local mode on the fly (L key).

• Split view with file list and diff preview
• Syntax highlighting with powered by tree-sitter
• Add inline comments and code suggestions on specific lines
• View and navigate review comments with jump-to-line
• Submit reviews (Approve / Request Changes / Comment)
• Vim-like symbol search(gd), on-the-fly file display and editing(gf)
• Git log view for browsing PR commits with diff preview
• CI checks status display with workflow details

• Fully configurable keybindings and editor
• Customizable AI-Rally prompt templates
• Customizable with any syntax highlighting theme.

• 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

cargo install octorus

Or install via mise:

mise use -g github:ushironoko/octorus

Or build from source:

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

# 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

# 5. Run AI Rally in headless mode (no TUI, CI/CD friendly)
or --repo owner/repo --pr 123 --ai-rally

# 6. Run headless AI Rally on local diff
or --local --ai-rally

# 7. Preview local working tree diff in real time
or --local

# 8. Open issue list
or --issue

# 9. Open specific issue directly
or --issue 10

or init creates global config:

• ~/.config/octorus/config.toml - Main configuration file
• ~/.config/octorus/prompts/ - Prompt template directory
• ~/.claude/skills/octorus/SKILL.md - Agent skill documentation (if ~/.claude/ exists)

or init --local creates project-local config:

• .octorus/config.toml - Project-local configuration (overrides global)
• .octorus/prompts/ - Project-local prompt templates

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

┌─────────────────┐
│  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

When --ai-rally is combined with --pr or --local, AI Rally runs in headless mode — no TUI is launched, all output goes to stderr, and the process exits with a code suitable for CI/CD pipelines.

# Headless rally on a specific PR
or --repo owner/repo --pr 123 --ai-rally

# Headless rally on local diff
or --local --ai-rally

# With custom working directory
or --repo owner/repo --pr 123 --ai-rally --working-dir /path/to/repo

JSON output (stdout):

Headless mode writes a JSON object to stdout on completion:

{
  "result": "Approved",
  "iterations": 2,
  "summary": "All issues resolved",
  "last_review": { ... },
  "last_fix": { ... }
}

Exit codes:

Headless policy (no human interaction possible):

CI/CD example (GitHub Actions):

- name: AI Rally Review
  run: |
    or --repo ${{ github.repository }} --pr ${{ github.event.pull_request.number }} --ai-rally

• 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
• Pause/Resume: Press p to pause the rally at the next checkpoint (between iterations). Press p again to resume. The header shows (Pausing...) while waiting and (PAUSED) when stopped
• Background Execution: Press b to run rally in background while continuing to browse files
• Auto Post: Set auto_post = true in [ai] config to skip confirmation prompts and automatically post review/fix comments to the PR

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.

Reviewer (read-only operations):

Reviewee (code modification):

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.

Local Diff Mode lets you preview your uncommitted changes (git diff HEAD) directly in the TUI — no pull request required. A file watcher detects changes in real time and refreshes the diff automatically.

# Start in local diff mode
or --local

# With auto-focus: automatically jump to the changed file on each update
or --local --auto-focus

When running in local mode, octorus watches your working directory for file changes (ignoring .git/ internals and access-only events). As soon as you save a file, the diff view updates automatically.

When --auto-focus is enabled (or toggled with F), octorus automatically selects and focuses the file that changed most recently. If you're in the file list, it transitions to the split view diff. The selection algorithm picks the nearest changed file relative to your current cursor position.

The header displays [LOCAL] in local mode, or [LOCAL AF] when auto-focus is active.

You can toggle between PR mode and Local mode at any time by pressing L:

PR mode ──[L]──► Local mode
  │                │
  │  UI state is   │  Starts file watcher
  │  saved/restored│  Shows git diff HEAD
  │                │
Local mode ──[L]──► PR mode

Your UI state (selected file, scroll position) is preserved across mode switches. If you started from a PR, pressing L in local mode returns you to that PR with its cached data.

The following features are disabled in local mode since there is no associated pull request:

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

# Editor for writing review body.
# Resolved in order: this value → $VISUAL → $EDITOR → vi
# Supports arguments: editor = "code --wait"
# editor = "vim"

[diff]
# Syntax highlighting theme for diff view
# See "Theme" section below for available options
theme = "base16-ocean.dark"
# Number of spaces per tab character in diff view (minimum: 1)
tab_width = 4
# Show background color on added/removed lines (default: true)
# bg_color = false

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

[git_ops]
# Maximum number of cached commit diffs (default: 20)
max_diff_cache = 20

[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:*)"]

# Auto-post review/fix comments to PR without confirmation prompt
# Default is false (asks for confirmation before posting)
# auto_post = true

You can create project-local configuration under .octorus/ in your repository root. This allows per-project settings that can be shared with your team via version control.

or init --local

This generates:

.octorus/
├── config.toml        # Project-local config (overrides global)
└── prompts/
    ├── reviewer.md    # Project-specific reviewer prompt
    ├── reviewee.md    # Project-specific reviewee prompt
    └── rereview.md    # Project-specific re-review prompt

Override behavior: Local values are deep-merged on top of global config. Only specify keys you want to override — unspecified keys inherit from global config.

# .octorus/config.toml — only override what you need
[ai]
max_iterations = 5
timeout_secs = 300

Prompt resolution order (highest priority first):

1. .octorus/prompts/ (project-local)
2. ai.prompt_dir (custom directory from config)
3. ~/.config/octorus/prompts/ (global)
4. Built-in defaults

Warning: When you clone or fork a repository that contains .octorus/, be aware that those settings were chosen by the repository owner — not by you. octorus applies the following safeguards to protect you:

• editor is always ignored in local config. It cannot be set per-project.
• AI-related settings (ai.reviewer, ai.reviewee, ai.*_additional_tools, ai.auto_post) and local prompt files will trigger a confirmation dialog before AI Rally starts. In headless mode, you must explicitly pass --accept-local-overrides to allow them.
• ai.prompt_dir cannot use absolute paths or .. in local config.
• Symlinks under .octorus/prompts/ are not followed.

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:

The [diff] section's theme option controls the syntax highlighting color scheme in the diff view.

[diff]
theme = "Dracula"

Theme names are case-insensitive (dracula, Dracula, and DRACULA all work).

If a specified theme is not found, it falls back to base16-ocean.dark.

You can add custom themes by placing .tmTheme (TextMate theme) files in ~/.config/octorus/themes/:

~/.config/octorus/themes/
├── MyCustomTheme.tmTheme
└── nord.tmTheme

The filename (without .tmTheme extension) becomes the theme name:

[diff]
theme = "MyCustomTheme"

Custom themes with the same name as a built-in theme will override it.

PRs are loaded with infinite scroll — additional PRs are fetched automatically as you scroll down. The header shows the current state filter (open/closed/all).

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:

Go to Definition (gd): When multiple symbol candidates are found, a popup appears for selection. Use j/k to navigate, Enter to jump, Esc to cancel. The jump stack (Ctrl-o to go back) stores up to 100 positions.

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.

Multiline Selection Mode:

Press Shift+Enter to enter multiline selection mode. Select a range of lines, then create a comment or suggestion spanning the entire range.

Comment Panel (when focused):

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.

The git ops view provides staging, committing, and commit history browsing in a single screen. The left pane is split vertically: file tree (70%) and commit history (30%). The right pane shows the diff preview.

Destructive operations (discard, undo, reset) show a Y/n confirmation prompt with the exact git command that will be executed. The commits pane title shows ↑N when local commits are ahead of the remote.

Can be opened directly from CLI with --git-ops flag.

Tree Focus:

Commits Focus:

Diff Focus:

Commits are loaded with infinite scroll. Diffs are prefetched in the background for faster navigation.

Status icons: ✓ (pass), ✕ (fail), ○ (pending), - (skipped/cancelled). Each check shows its name, workflow, and duration.

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"]

Press Space / in the PR list or file list to activate keyword filtering. Type to filter items by name.

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

MIT