octo.nvim: GitHub Issue and Pull Request Management Inside Neovim

What octo.nvim Does and Why It Differs from the GitHub Web Interface

The GitHub web interface opens each issue or pull request in a browser tab, with its own text editor, label picker, and reviewer UI. Switching to the browser and back costs focus, especially for engineers who work inside Neovim for most of their day. octo.nvim loads a GitHub issue or pull request directly into a Neovim buffer, where you edit the title, body, and comments as plain text and use :w to write the changes back to GitHub.

The plugin also handles metadata: you can add or remove labels, reactions, assignees, project cards, and reviewers from within Neovim. Pull request reviews are supported, including inline comments on diff hunks. The README describes the workflow as treating GitHub objects the same way Neovim treats any file.

How Editing Syncs with GitHub via :w

When you open an issue or pull request through octo.nvim, the plugin populates a buffer with the title, description, comments, and metadata fetched through the GitHub CLI. Editing happens in that buffer using standard Neovim motion and insert commands. Running :w on the buffer sends the changes back to GitHub.

From any octo buffer, pressing Enter in normal mode shows a list of common actions for the current context. This provides a discoverable way to apply metadata changes (adding a label, assigning a reviewer) without memorizing the full command list.

The plugin uses the GitHub CLI as its transport layer. All GitHub API calls go through gh, which means authentication is handled by the CLI's existing token management rather than a separate plugin-level credential store.

Requirements and Installation with lazy.nvim

octo.nvim requires Neovim 0.10.0 or later. Required dependencies are the GitHub CLI and plenary.nvim. A picker plugin is optional but recommended: the README supports telescope.nvim, fzf-lua, and snacks.nvim, with vim.ui.select as the default if none is installed. nvim-web-devicons is optional for file panel icons.

For Projects v2 support, the gh token needs the read:project scope. The README gives the command to add it:

gh auth refresh -s read:project

A lazy.nvim installation with telescope as the picker:

{
  "pwntester/octo.nvim",
  cmd = "Octo",
  opts = {
    -- or "fzf-lua" or "snacks" or "default"
    picker = "telescope",
    -- bare Octo command opens picker of commands
    enable_builtin = true,
  },
  keys = {
    {
      "<leader>oi",
      "<CMD>Octo issue list<CR>",
      desc = "List GitHub Issues",
    },
    {
      "<leader>op",
      "<CMD>Octo pr list<CR>",
      desc = "List GitHub PullRequests",
    },
  },
}

After installation, run :checkhealth octo to verify the GitHub CLI is found and authenticated.

The Octo Command Interface and the octo:// URL Scheme

The entire plugin surface is exposed through one command: `Octo <object> <action> [arguments]`. Objects include issue, pr, comment, label, reaction, assignee, reviewer, and others. Actions are subcommands specific to each object. When no command is passed, the argument is treated as a URL.

GitHub URLs can be opened directly:

Octo https://github.com/pwntester/octo.nvim/issues/12
Octo https://github.com/pwntester/octo.nvim/pull/123

The plugin also registers an `octo://` URI handler, so you can open issues or pull requests from Neovim's file commands regardless of your current working directory:

:e octo://owner/repo/issue/123
:e octo://owner/repo/pull/456

The octo:// scheme is useful for opening links from notes or wiki buffers, and for working with multiple GitHub instances without setting the GH_HOST environment variable globally. Both singular and plural forms (issues, pulls) are accepted.

GitHub Enterprise Support and Multiple Instance Workflows

octo.nvim handles GitHub Enterprise URLs by detecting the hostname automatically. You can open an Enterprise issue with the full URL:

Octo https://ghe.example.com/owner/repo/issues/456

The octo:// scheme also supports Enterprise instances by including the hostname:

:e octo://ghe.example.com/owner/repo/issue/123

This means a developer working across github.com and an internal Enterprise instance can keep both open in Neovim buffers without setting a global GH_HOST variable. The README notes that hostname detection is automatic, based on the URL passed to the command.

Pull Request Review Workflow Inside Neovim

Pull request reviews in octo.nvim allow you to add inline comments to diff hunks and submit a review without leaving Neovim. The README lists this as a first-class feature. Reviewers can also be added and removed through the `Octo reviewer add` and related commands.

The search interface accepts GitHub's query syntax. The README examples show filtering by assignee, labels, state, and content:

Octo issue list neovim/neovim labels=bug,help\ wanted states=OPEN
Octo search assignee:pwntester is:pr
Octo search is:discussion repo:pwntester/octo.nvim category:"Show and Tell"

This means the full power of GitHub search is available from the command line without context-switching. Results open in the configured picker (telescope, fzf-lua, snacks, or the default vim.ui.select).

Where octo.nvim Does Not Reach

The plugin is documented only for GitHub and GitHub Enterprise. The RELATED SEARCHES for this project include terms about GitLab and Bitbucket, and the README is silent on both. Teams using GitLab or Bitbucket have no equivalent path through octo.nvim.

The GitHub CLI is a hard dependency. There is no built-in OAuth flow or token entry in octo.nvim itself. If the CLI is not installed, authenticated, or able to reach GitHub, the plugin will not work. Teams with restricted network environments that block the gh binary will need to investigate CLI proxy configuration before adopting octo.nvim.

File panel icon display depends on nvim-web-devicons or a configured alternative. Without it, icons are absent but functionality is unaffected. The README allows providing a custom function returning an icon and highlight group, which is the documented path for teams using a different icon library such as mini.icons.

Maintenance and License

The last push to the repository was on 2026-08-28. The repository is not archived. The project includes a contributing guide, a code of conduct, and a Makefile with a target for generating configuration documentation from the Lua source. Type checking runs through lua-language-server against the lua/octo directory.

The project is released under the MIT license. There are no GitHub releases; installation is from the master branch through a plugin manager.

Editorial conclusion

octo.nvim suits Neovim developers who spend significant time triaging issues or reviewing pull requests and want to reduce context-switching to the browser. Teams using GitLab or Bitbucket cannot use it: the README documents GitHub and GitHub Enterprise support only. Before deploying it to a team, verify the GitHub CLI is installed and authenticated on each machine by running :checkhealth octo.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pwntester/octo.nvim on GitHub
4. README