Harpoon — Quick File Switching

Harpoon (by ThePrimeagen) lets you "pin" up to N files and jump between them with a single keypress. It replaces the tab metaphor for your working file set.

Core Idea

In any project you are actively editing, you touch 3-5 files most of the time. Harpoon pins those files and gives you instant numbered access to them — no fuzzy search needed.

Installation

lua/plugins/harpoon.lua

return {
  {
    "ThePrimeagen/harpoon",
    branch = "harpoon2",
    dependencies = { "nvim-lua/plenary.nvim" },
    config = function()
      local harpoon = require("harpoon")
      harpoon:setup({
        settings = {
          save_on_toggle = true,
          sync_on_ui_close = true,
        },
      })

      local map = vim.keymap.set

      -- Add current file to harpoon
      map("n", "<leader>ha", function() harpoon:list():add() end, { desc = "Harpoon: add file" })

      -- Open quick menu
      map("n", "<leader>hh", function()
        harpoon.ui:toggle_quick_menu(harpoon:list())
      end, { desc = "Harpoon: quick menu" })

      -- Jump to pinned files by number
      map("n", "<leader>1", function() harpoon:list():select(1) end, { desc = "Harpoon: file 1" })
      map("n", "<leader>2", function() harpoon:list():select(2) end, { desc = "Harpoon: file 2" })
      map("n", "<leader>3", function() harpoon:list():select(3) end, { desc = "Harpoon: file 3" })
      map("n", "<leader>4", function() harpoon:list():select(4) end, { desc = "Harpoon: file 4" })
      map("n", "<leader>5", function() harpoon:list():select(5) end, { desc = "Harpoon: file 5" })

      -- Navigate: previous / next
      map("n", "[h", function() harpoon:list():prev() end, { desc = "Harpoon: prev" })
      map("n", "]h", function() harpoon:list():next() end, { desc = "Harpoon: next" })
    end,
  },
}

The Harpoon Workflow

1. Open a file you plan to revisit frequently
2. Press <leader>ha       → add to harpoon list
3. Repeat for 2-4 more files

4. Press <leader>hh        → see your pinned list (quick menu)
5. Press <leader>1         → instantly jump to file 1
6. Press <leader>3         → instantly jump to file 3

Inside the Quick Menu

The quick menu is a small floating window listing your pinned files:

(1) lua/config/lsp.lua
(2) lua/plugins/telescope.lua
(3) lua/config/keymaps.lua
(4) tests/api_test.lua

Keys inside the menu:

Enter    → open file under cursor
q        → close
d        → delete file from list (remove pin)
reorder  → simply rearrange lines to reorder

Why Harpoon + Telescope Together

Use Case	Tool
Jump to your 3 main files being edited	Harpoon
Find a file you haven't opened yet	Telescope
Search across the project	Telescope live_grep
Browse unknown directory	Neo-tree

The combination is: Harpoon for your working set, Telescope for everything else.

What's Next

• Gitsigns
• Neogit