Jumper - Directory Bookmarks for Your Shell

Jumper lets you bookmark directories and jump to them by name from anywhere in your shell. No more cd ../../some/deeply/nested/project — just jump proj.

Inspired by zshmarks, Jumper is a standalone Go binary with shell integration, case-insensitive subdirectory tab-completion, and Table/JSON/YAML output.

Table of Contents

• Installation
• Shell Setup
• Quick Start
• jump Behaviour
• Tab Completion
• Data Storage
• Agent Integration

Installation

Homebrew (macOS and Linux):

brew install AmrSaber/tap/jumper

Go:

go install github.com/AmrSaber/jumper@latest

Shell Setup

Jumper provides a shell integration script that defines the jump function (which handles the cd for you). Add one line to your shell's rc file:

eval "$(jumper init)"

Jumper auto-detects your shell from $SHELL. You can also pass it explicitly:

eval "$(jumper init zsh)"   # ~/.zshrc
eval "$(jumper init bash)"  # ~/.bashrc

Then reload your shell:

source ~/.zshrc   # or ~/.bashrc

Only jump is a shell function — all other commands (jumper mark, jumper delete, etc.) are invoked directly.

Quick Start

# Bookmark the current directory using its base name
cd ~/Projects/my-app
jumper mark           # saves as "my-app"

# Bookmark the current directory with an explicit name
jumper mark my-app

# Bookmark a specific directory without cd-ing into it
jumper mark my-app ~/Projects/my-app

# Jump to a bookmark from anywhere
jump my-app

# Jump into a subdirectory directly
jump my-app/src/components

# Jump back to the previous directory (like cd -)
jump -

# List all bookmarks (also: jump with no arguments)
jumper list
# ┌──────────┬───────────────────────────┐
# │ TITLE    │ PATH                      │
# ├──────────┼───────────────────────────┤
# │ dotfiles │ ~/.dotfiles [not found]   │
# │ my-app   │ ~/Projects/my-app         │
# └──────────┴───────────────────────────┘
# Paths that no longer exist are flagged with [not found] in table output.
# Use --output json or --output yaml for machine-readable output.
jumper list --output json
jumper list --output yaml

# Rename a bookmark
jumper rename my-app app

# Delete a bookmark by name
jumper delete dotfiles

# Delete multiple bookmarks by name
jumper delete dotfiles my-app

# Delete all bookmarks pointing to a specific directory
jumper delete ~/Projects/my-app

# Delete all bookmarks pointing to the current directory
jumper delete           # or: jumper delete .

# Remove all bookmarks whose paths no longer exist
jumper prune            # or: jumper clean

# Print the resolved path for a bookmark (useful in scripts)
jumper resolve my-app
jumper resolve my-app/src/components

# Use `jumper help` to get the full help

jump Behaviour

Invocation	Result
jump <bookmark>	cd to the bookmarked directory
jump <bookmark>/sub/dir	cd into a subdirectory of the bookmark
jump -	cd back to the previous directory
jump	display all bookmarks (calls jumper list)
jump a b	error with usage message

- is a reserved name and cannot be used as a bookmark name.

Tab Completion

The jump function supports tab completion for bookmark names and subdirectories.

• Bookmark names are matched case-insensitively — typing proj matches Projects
• A trailing / is appended to each completion so you can keep chaining without extra keystrokes
• Subdirectory expansion works at any depth, also case-insensitively

jump pro<Tab>         → jump Projects/
jump Projects/<Tab>   → jump Projects/src/
                        jump Projects/docs/
jump Projects/sr<Tab> → jump Projects/src/

Data Storage

Bookmarks are stored as a JSON file at your system's standard data location:

• Linux: $XDG_DATA_HOME/jumper/bookmarks.json (defaults to ~/.local/share/jumper/bookmarks.json)
• macOS: ~/Library/Application Support/jumper/bookmarks.json

The file is a plain JSON array — easy to inspect, back up, or sync with your dotfiles.

[
  { "title": "dotfiles", "path": "/home/amr/.dotfiles" },
  { "title": "app", "path": "/home/amr/Projects/my-app" }
]

---

Agent Integration

Jumper ships an integration for coding agents so they always know your current bookmarks (name → path) and how to manage them. Installing it writes two files into the agent's config: a skill describing the bookmark-management commands, and a plugin that feeds the live bookmark list into each turn.

# Install the integration
jumper agent setup opencode

# Remove it (deletes only the files jumper wrote)
jumper agent cleanup opencode

For OpenCode this writes ~/.config/opencode/skills/jumper/SKILL.md and ~/.config/opencode/plugins/jumper-inject.ts. Re-run setup to update them after upgrading jumper.

---

Contributing

1. Fork the repository
2. Create a feature branch (git switch -c feature/my-feature)
3. Commit your changes
4. Open a Pull Request

For bug reports and feature requests, please create a ticket.