octorus

<p align="center"> <img src="assets/banner.png" alt="octorus banner" width="600"> </p>

High-performance code review in your terminal for GitHub PRs, issues, local diffs, CI status, and Git operations. Includes an integrated AI-powered review cycle.

Key Features

• Fast and smooth: Handles 1,000,000+ diff lines and 6,000+ files
• Multifunctional: PR review, issue view, local diff view, CI status, and Git operations are integrated into one system with search, filters, comments, suggestions, and more.
• Automatic Review and Code Fix: Automated review and fix workflows for Claude and Codex, while keeping the process under your control
• Customization: Customize all settings, including keybindings, themes, and agent prompts

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 install via mise:

mise use -g github:ushironoko/octorus

Usage

# 1. Initialize config
or init

# 2. Open the Cockpit dashboard (default when no flags are given)
or

# 3. Open a specific PR directly
or --pr 123

# 4. Preview local changes
or --local

Options

| Option | Description | |--------|-------------| | -r, --repo <REPO> | Repository name (e.g., owner/repo). Auto-detected from current directory if omitted | | -p, --pr [<PR>] | Open PR list (flag only), or open a specific PR directly if number is provided | | -i, --issue [<ISSUE>] | Open issue list (flag only), or open a specific issue directly if number is provided | | --local | Show local git diff against current HEAD (no GitHub PR fetch) | | --ai-rally | Start AI Rally mode directly. Runs in headless mode when combined with --pr <number> or --local | | --git-ops | Open Git Ops view directly on startup | | --auto-focus | Auto-focus changed file when local diff updates (local mode only) | | --working-dir <DIR> | Working directory for AI agents (default: current directory) | | --accept-local-overrides | Accept local .octorus/ overrides for AI settings in headless mode | | --output <FILE> | Write JSON result to a file in addition to stdout (headless mode) |

Subcommands

| Subcommand | Description | |------------|-------------| | or init | Initialize global configuration files, prompt templates, and agent SKILL.md | | or init --local | Initialize project-local .octorus/ config and prompts | | or init --force | Overwrite existing configuration files | | or clean | Remove AI Rally session data |

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

Reviewing Code in your Terminal

octorus is an all-in-one review tool for the terminal UI. It shows GitHub PRs, issues, CI status, local diffs, Git Ops, and AI-Rally.

Cockpit

Running or with no flags opens the Cockpit — a dashboard that serves as the main entry point.

• Live counts: issues mentioning you and PRs requesting your review
• Navigation menu to PR List, Issue List, Local Diff, and Git Ops
• Press Enter to navigate, q to quit, ? for help, r to refresh counts
• When no GitHub repo is detected, remote features (PR List, Issue List) are disabled; Local Diff and Git Ops remain available

Pull Requests

• Infinite scroll PR list with state filter (open / closed / all)

• Split view: file list (35%) + diff preview (65%), focused pane highlighted
• Syntax highlighting powered by tree-sitter
• Inline comments and code suggestions on specific lines
• Multiline selection mode (Shift+Enter) for range comments and suggestions
• Show Comment List for Review Comments and Discussions
• Review submission (Approve / Request Changes / Comment)
• Mark files and directories as viewed
• File tree view toggle
• Go to Definition (gd) with symbol popup and jump stack (up to 100 positions)
• Go to File (gf) open file at cursor line in external editor (editor config → $VISUAL → $EDITOR → vi)
• Keyword filter for PR list and file list
• Show PR Description with Markdown renderer
• Open PR in browser

Issues

• Infinite scroll issue list with state filter (open / closed / all)

• Issue detail view with Markdown renderer
• Linked PR navigation — jump directly to a linked PR
• Issue comment list and comment detail view
• Keyword filter
• Open issue in browser

CI Status

• CI checks list with workflow name and duration
• Status icons: ✓ (pass), ✕ (fail), ○ (pending), - (skipped/cancelled)
• Open check run in browser

Local Diff

• Preview uncommitted changes (git diff HEAD) without creating a PR
• Real-time file watching — diff refreshes automatically on save (ignoring .git/ internals)
• Auto-focus mode (--auto-focus or F key) — automatically selects the most recently changed file
• Header shows [LOCAL] or [LOCAL AF] when auto-focus is active

or --local
or --local --auto-focus

Git Ops

• Show staging, committing, and commit history
• Tree pane (70%) + commit history pane (30%) + diff preview
• Stage/unstage individual files or directories
• Discard, undo, soft-reset with Y/n confirmation showing the exact git command
• Push to origin
• Infinite scroll commit history

Zen mode

Zen mode displays the interface in fullscreen. Toggle it with the Z key.

This is especially effective on small screens.

Shell Command

Press ! to enter shell command mode and execute any shell command.

• Runs asynchronously in the working directory
• Not available during text input, filter input, or modal dialogs
• Output is truncated at 1 MB
• Timeout: configurable via [shell].timeout_secs (default: 10 seconds)

AI Rally

• Automated PR review and fix cycle using two AI agents
• Reviewer: analyzes the PR diff and provides review feedback
• Reviewee: fixes issues based on the review feedback and commits changes
• Permission and clarification prompts during the cycle
• Pause / resume / retry / run in background

Headless Mode (CI/CD)

When --ai-rally is combined with --pr or --local, AI Rally runs in headless mode — no TUI is launched, all output goes to stderr.

# 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

Exit codes:

| Code | Meaning | |------|---------| | 0 | Reviewer approved | | 1 | Not approved (request changes, error, or abort) |

Headless policy (no human interaction possible):

| Situation | Behavior | |-----------|----------| | Clarification needed | Auto-skip (agent proceeds with best judgment) | | Permission needed | Auto-deny (prevents dynamic tool expansion) | | Post confirmation | Auto-approve (posts review/fix to PR) | | Agent text/thinking | Suppressed (prevents JSON leakage to stdout) |

Recommended Configuration

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

| Role | Recommended | Reason | |------|-------------|--------| | Reviewer | Codex or Claude | Read-only operations, both are safe | | Reviewee | Claude | Allows fine-grained tool control via allowedTools |

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):

| Tool | Description | |------|-------------| | Read, Glob, Grep | File reading and searching | | gh pr view/diff/checks | View PR information | | gh api --method GET | GitHub API (GET only) |

Reviewee (code modification):

| Category | Commands | |----------|----------| | File | Read, Edit, Write, Glob, Grep | | Git | status, diff, add, commit, log, show, branch, switch, stash | | GitHub CLI | pr view, pr diff, pr checks, api GET | | Cargo | build, test, check, clippy, fmt, run | | npm/pnpm/bun | install, test, run |

Additional Tools (Claude only)

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

| Example | Description | |---------|-------------| | "Skill" | Execute Claude Code skills | | "WebFetch" | Fetch URL content | | "WebSearch" | Web search | | "Bash(git push:*)" | git push to remote | | "Bash(gh api --method POST:*)" | GitHub API POST requests |

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

octorus skills

Recommended setup for coding agents. Run the or init subcommand to create the skill file in ~/.claude/skills/octorus.

You can instruct the agent with "/octorus ai-rall