Skip to main content
This guide will get you up and running with Harpoon quickly. You’ll learn how to mark files and navigate between them using the most common workflows.
Make sure you’ve installed Harpoon before following this guide.

​
Set up keybindings

1

Add basic keybindings to your config

Open your Neovim configuration file (usually ~/.config/nvim/init.lua or ~/.config/nvim/lua/config/keymaps.lua) and add these keybindings:
local mark = require("harpoon.mark")
local ui = require("harpoon.ui")

-- Add current file to Harpoon
vim.keymap.set("n", "<leader>a", mark.add_file, { desc = "Harpoon: Add file" })

-- Toggle the Harpoon quick menu
vim.keymap.set("n", "<C-e>", ui.toggle_quick_menu, { desc = "Harpoon: Toggle menu" })

-- Navigate to Harpoon marks 1-4
vim.keymap.set("n", "<C-h>", function() ui.nav_file(1) end, { desc = "Harpoon: Go to file 1" })
vim.keymap.set("n", "<C-t>", function() ui.nav_file(2) end, { desc = "Harpoon: Go to file 2" })
vim.keymap.set("n", "<C-n>", function() ui.nav_file(3) end, { desc = "Harpoon: Go to file 3" })
vim.keymap.set("n", "<C-s>", function() ui.nav_file(4) end, { desc = "Harpoon: Go to file 4" })
These are the keybindings used by ThePrimeagen (Harpoon’s creator), but you can customize them to your preference. Just make sure they don’t conflict with your existing keybindings.
2

Reload your configuration

Save the file and reload your Neovim configuration:
:source %
Or restart Neovim.

​
Your first marks

1

Open a file you work with frequently

Navigate to any file in your project that you want to mark. For example:
:e src/index.js
2

Mark the file

With the file open, press <leader>a (or whatever keybinding you configured for mark.add_file).You should see a message: Mark addedThis adds the current file to your Harpoon marks at the first available slot.
3

Mark additional files

Open 2-3 more files that you work with frequently and mark each one with <leader>a.For example:
:e src/components/Header.jsx
" Press <leader>a

:e src/utils/helpers.js  
" Press <leader>a

:e tests/integration.test.js
" Press <leader>a
Each file gets added to the next available mark slot (1, 2, 3, 4, etc.).
1

Open the quick menu

Press <C-e> to toggle the Harpoon quick menu.You’ll see a popup window showing all your marked files:
1  src/index.js
2  src/components/Header.jsx
3  src/utils/helpers.js
4  tests/integration.test.js
The currently open file will be highlighted.
2

Navigate from the menu

From the quick menu, you can:
  • Navigate to a file: Move your cursor to any line and press Enter
  • Open in vertical split: Press <C-v>
  • Open in horizontal split: Press <C-x>
  • Open in new tab: Press <C-t>
  • Delete a mark: Delete the line with dd
  • Reorder marks: Cut with dd and paste with p
  • Close the menu: Press q or <ESC>
Changes to the menu (reordering, deleting) are saved automatically when you close it.
3

Navigate with direct keybindings

Close the quick menu and try navigating directly to marks using the keybindings you set up:
  • Press <C-h> to jump to mark 1 (src/index.js)
  • Press <C-t> to jump to mark 2 (src/components/Header.jsx)
  • Press <C-n> to jump to mark 3 (src/utils/helpers.js)
  • Press <C-s> to jump to mark 4 (tests/integration.test.js)
This is the real power of Harpoon: instant navigation to your most important files without thinking.

​
Cycle through marks

You can also cycle through all your marks sequentially: 
-- Add these to your keybindings
vim.keymap.set("n", "<C-S-P>", ui.nav_prev, { desc = "Harpoon: Previous mark" })
vim.keymap.set("n", "<C-S-N>", ui.nav_next, { desc = "Harpoon: Next mark" })
Now you can:
  • Press <C-S-N> to go to the next mark
  • Press <C-S-P> to go to the previous mark
The navigation wraps around, so from the last mark, next takes you to the first.

​
Common workflows

​
Working on a feature

  1. Mark the main files you’ll be editing:
    • The feature implementation file
    • The test file
    • Related configuration or types
  2. Use direct keybindings (<C-h>, <C-t>, etc.) to jump between them as you work
  3. When you’re done, open the quick menu (<C-e>) and clear marks with dd if needed

​
Bug fixing

  1. Mark the file where the bug is reported
  2. As you trace through the code, mark related files
  3. Use <C-S-N> and <C-S-P> to cycle through the call stack
  4. Jump back to the main file with the direct keybinding

​
Code review

  1. Mark files from the pull request that need attention
  2. Navigate through them systematically with direct keybindings
  3. Use the quick menu to see which files you haven’t checked yet
Marks are saved per project (based on your current working directory). If you change projects, you’ll have a different set of marks.

​
What’s next?

You now know the core Harpoon workflow! Explore more advanced features:

File navigation

Learn advanced mark management and navigation patterns

Terminal navigation

Use Harpoon to manage persistent terminals

Configuration

Customize Harpoon’s behavior and appearance

Telescope integration

Browse marks with Telescope

Build docs developers (and LLMs) love

Get started for freeTalk to us