octorus

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: Repository browsing, PR review, issue view, local diff view, CI status, and Git operations are integrated into one system with search, filters, comments, suggestions, and more.
• Code intelligence without an LSP: tree-sitter symbol index powers file outlines, repository-wide symbol search, and Go to Definition — no language server to install, nothing to configure
• 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.95+ (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

# 5. Browse the repository (read any file, jump by symbol)
or --browse

Options

Subcommands

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, Git Ops, and Repo Browse
• 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, Git Ops, and Repo Browse remain available

Repository Browser

octorus is not only a review tool — or --browse (or b from the file list, or Repo Browse in the Cockpit) opens the whole repository read-only.

• Browse every file, not just the ones a PR touched — tracked and untracked files included, ignored files excluded, uncommitted files visible immediately
• Same tree-sitter syntax highlighting as the diff view (24 languages, your configured theme, Vue/Svelte/Markdown injections)
• Long lines wrap at the pane edge onto gutter-aligned continuation rows, breaking on character boundaries so CJK prose wraps cleanly
• Markdown rich display (M) — the same rich rendering as the diff view, applied to the open markdown file
• Background loading — listing the repository, reading a file, and highlighting never block the UI
• Blame gutter (gb) with jump to the blamed commit's diff (gc) or the PR that introduced it (gp)
• Review discussion anchoring (gr) — marks the lines a PR review discussed and opens the thread at the cursor line; threads are placed by blame origin, so lines edited or moved since the review may not be matched
• Read-only — gf opens the file in your editor (editor config → $VISUAL → $EDITOR → vi) at the cursor line
• Keyword filter for the file tree (Space /)
• Render limits with explicit notices: over 8 MiB, over 100,000 lines, or a single line over 10,000 bytes; binary and empty files are labelled instead of rendered
• Works without a GitHub remote — only the PR- and issue-backed screens need one

or --browse

Symbol Intelligence

octorus indexes the repository in the background using tree-sitter tags.scm queries — no language server to install and nothing to configure; the grammars are compiled into the binary. The header shows the index state (symbols: indexing / ready / unavailable), and browsing never waits for it.

Symbol extraction covers Rust, TypeScript, TSX, JavaScript, JSX, Go, Python, Ruby, C, C++, Java, C#, Lua, PHP, Swift, Bash, Zig, Haskell, MoonBit, and Markdown (headings become the outline of a README).

The module graph supports Rust, TypeScript, TSX, JavaScript, and JSX. JavaScript/TypeScript imports resolve relative paths, packages, and a root tsconfig.json or jsconfig.json; Rust resolution is best-effort. Each direction shows up to 200 nodes, every answer is labelled exact or approximate, and the pane follows file navigation.

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
• Readline-style editing keys (Ctrl-A/E/B/F/P/N/D/H/K/U/W) inside the comment / reply / suggestion text input
• 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
• Local comments — leave review comments on your own diff, persisted to disk across sessions
• Header shows [LOCAL] or [LOCAL AF] when auto-focus is active

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

Local Comments

In local mode, you can leave review comments on diff lines just like on a GitHub PR. Comments are saved to ~/.cache/octorus/local-comments/ and persist across sessions, scoped by repo and working directory.

• Press c on a diff line to add a comment, s for a suggestion, r to reply
• Press C to view all local comments in the comment list
• Comments can be resolved and reopened

Local comments can also seed AI Rally — when you start a rally in local mode, any open local comments are passed to the reviewer as a starting point, skipping the initial review step.

CLI subcommands for managing local comments outside the TUI:

# Show open local comments (auto-detects repo)
or local-comments

# Show all comments including resolved
or local-comments --all

# Show as JSON
or local-comments --json

# Resolve a comment
or update-local-comment --resolve 3

# Reopen a comment
or update-local-comment --reopen 3

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
• Starts without a GitHub remote — or --git-ops reads status and commit history from the local repository alone

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

Review Only Mode

Use --ai-rally --review-only=true to run AI Rally in proposal-iteration mode. The reviewee never modifies code — instead it produces a written fix proposal which the reviewer re-reviews. Useful when you want a vetted plan rather than direct commits, or when the working tree must stay untouched.

You can also set ai.review_only = true in config, but the CLI flag is the explicit per-run override.

Flow:

1. Reviewer reviews the PR diff (same as normal mode).
2. If the reviewer approves → rally ends.
3. Otherwise the reviewee produces a RevieweeProposal using read-only tools only (no Bash, Edit, Write, NotebookEdit).
4. The reviewer re-reviews the proposal.
5. Loop continues until reviewer approves or max_iterations is hit.

The TUI header shows a [Review Only] badge while the mode is active.

Tool boundary: The proposal step runs under a hard read-only boundary (base allowlist Read,Glob,Grep; mutating tools are denied at the agent layer). Extra read-only tools can be added via ai.reviewee_proposal_additional_tools — any entry that would re-introduce a mutating tool is rejected at startup.

Posting proposals: ai.post_reviewee_proposals controls when proposals are posted to the PR — "final" (default) posts only the last proposal, "each" posts every iteration, "none" keeps them in session history only.

[ai]
review_only = true
post_reviewee_proposals = "final"
reviewee_proposal_additional_tools = ["WebSearch"]  # optional, read-only only

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 review-only rally on a specific PR
or --repo owner/repo --pr 123 --ai-rally --review-only=true

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

Headless policy (no human interaction possible):

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

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-rally in local".

Configuration

All octorus settings are configurable. Settings can be global or project-local.

Settings Reference

Top-level

[diff]

[layout]

[mouse]

[ai]

[git_ops]

[shell]

[keybindings]

See Configurable Keybindings for the full list. Three formats are supported:

[keybindings]
move_down = "j"                          # Simple key
page_down = { key = "d", ctrl = true }   # Key with modifier
go_to_definition = ["g", "d"]            # Two-key sequence

Global Configuration

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

Project-Local Configuration

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.

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:

Theme

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

Built-in Themes

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

Custom Themes

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.

Keybindings

Mouse

Mouse support works on every screen and follows the same paths as the keyboard, so lazy loading, prefetching, and state transitions behave identically.

Copying text: while mouse capture is on, the terminal's native drag-to-select is unavailable. Press F2 to release the mouse, copy, then press F2 again (many terminals also support Shift+drag as a bypass). Set [mouse] enabled = false to disable mouse support entirely.

PR List View

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

File List View

Split View

The split view shows the file list (left) and a diff preview (right). The default ratio is 35%/65%, configurable via layout.left_panel_width. The focused pane is highlighted with a yellow border.

File List Focus:

Diff Focus:

Diff View

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

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.

Repository Browser View

The repository browser shows the file tree (left) and file content (right), with an optional UML module graph pane on the far right; the file outline and symbol search open as overlays. Keys depend on which pane has focus. The focused pane is highlighted with a yellow border.

This view can be opened with b from the file list, Repo Browse in the Cockpit, or directly from the CLI with the --browse flag.

Tree Focus:

File Focus:

Outline / Symbol Search Overlay:

Module Graph Focus:

Git Ops View

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.

This view can be opened directly from the CLI with the --git-ops flag.

Tree Focus:

Commits Focus:

Diff Focus:

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

CI Checks View

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

Issue List View

Issue Detail View

Issue Comment List View

Comment List View

AI Rally View

Shell Command Input

Shell Command Running

Shell Command Output

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 }

# Named key (PageDown / PageUp / etc.)
diff_page_down = "PageDown"
diff_page_up = "PageUp"

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

Available Keybindings

Keyword Filter

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.

Design Docs

Technical reference documents for the Repository Browser and its code-intelligence engines live in docs/:

docs/README.md indexes the same two documents from inside the directory.

License

MIT