jumbit

A MoonBit rewrite of zoxide: jump to directories in a few keystrokes, jump + Moonbit

cd ~/projects/backend     # work as usual; cd is recorded automatically
cd ~/somewhere/else
j backend                 # one keyword gets you back to ~/projects/backend
ji                        # or pick interactively with fzf

Why

zoxide turns "the places you have cd-ed through" into "one keyword and you are back" via frecency (frequency × time decay), a staple of the modern shell. jumbit rewrites these long-proven semantics from scratch in MoonBit: no upstream code is carried over, and behavior is aligned item by item with zoxide 0.10.0, including decay factors, keyword matching, aging, exit codes, and the fzf channel, backed by million-row, byte-level parity runs against the real upstream binary (BENCHMARKS.md)

On that foundation, jumbit extends directory memory beyond the shell: coding agents are the new "heavy cd users", and jumbit gives them machine-readable queries, human annotations, a project map, and an MCP server, so that an agent opening the workspace immediately knows the directory layout and purpose

Features

• Keyword jumping: j backend, j backend api, ranked by frecency; the last keyword anchors the final path component, the rest are consumed right-to-left (semantics aligned with upstream)
• 9-shell integration: nine templates including bash / zsh / fish; directories are recorded on cd, j/ji (fzf interactive) and completion work out of the box
• Agent channels: byte-stable --json/--tsv output (with the matched_by evidence field), describe human annotations persisted in the database, export --agents project-map Markdown, and jumbit mcp, a stdio MCP server exposing the jumbit_query/jumbit_export_agents tools plus server instructions (verified against the official SDK client)
• History migration: one-command import from z / zsh-z / z.lua / autojump / fasd / atuin: direct pour into an empty database, --merge otherwise, bad rows never abort the run
• Tool ecosystem: sesh (tmux session manager) can swap its frecency backend wholesale; yazi becomes a directory-memory collector through a wrapper function
• Data self-check and editing: status shows the database at a glance (entries/notes/format/aging threshold), edit rewrites the database with an editor or --rename/--prune directly, --json for scripts

Install

Option 1: one-line install script (recommended, no toolchain needed): prebuilt coverage: Linux x86_64 / macOS Apple Silicon / Windows x64

curl -fsSL https://github.com/superbigcup325/jumbit/releases/latest/download/install.sh | sh

Installs to ~/.local/bin (the script hints if it is not on your PATH; JUMBIT_INSTALL_DIR picks another directory, JUMBIT_VERSION or a positional argument pins a version, defaults to latest); Windows does not use the script — grab the windows-x86_64 zip from Releases, unzip, and put it on your PATH (the executable is named jumbit)

Option 2: mooncakes (requires the MoonBit toolchain)

moon install superbigcup325/jumbit/cmd/jumbit   # install the binary globally

Note: the binary lands at ~/.moon/bin/jumbit, matching the executable name, ready to use right away (~/.moon/bin is already on your PATH, otherwise the moon command itself would not run)

Option 3: build from source (anchored at moon 0.1.20261016; CI pins this version for reproducible builds):

git clone https://github.com/superbigcup325/jumbit && cd jumbit
export PATH="$HOME/.moon/bin:$PATH"   # MoonBit toolchain
moon check && moon test               # optional pre-build self-check
moon build --release
cp _build/native/release/build/cmd/jumbit/jumbit.exe ~/.local/bin/   # or any directory on your PATH

Toolchain anchor: CI pins reproducible builds via the MOONBIT_VERSION constant in .github/workflows/ci.yml; when upgrading the toolchain, bump that constant in the same change and rerun the full verification suite (regression/golden/dataset/chaos/realdata) — the constant is the single source of truth for the version

Quick start

# 1. Shell integration (bash shown; zsh/fish etc. see USAGE.md)
echo 'eval "$(jumbit init bash)"' >> ~/.bashrc && exec bash
# 2. Work as usual; directories are recorded automatically on cd
cd ~/projects/backend
# 3. Jump back by keyword from anywhere
j backend        # highest-ranked recorded directory matching backend
ji               # interactive jump with fzf (requires fzf)

Recording is fully automatic: the shell hook calls jumbit add whenever you change directories; to watch it record, export _JB_ECHO=1

Minimal command set

jumbit add ~/projects/backend        # record a directory (hook-invoked; manual use is fine)
jumbit query backend                 # print the best-matching directory
jumbit query --list --score          # all matches, ranked, with score prefix
jumbit describe ~/projects/backend --note "backend service"   # human annotation (jumbit extension)
jumbit status                        # database self-check (jumbit extension)
jumbit remove ~/projects/backend     # remove from the database
jumbit help                          # every command and flag

Documentation

• USAGE.md: full reference, including complete command/flag tables, shell-integration options and j/ji behavior, agent channels (--json/--tsv/tool registration schema), sesh/yazi setup, six-plugin import, frecency/aging/matching semantics, environment variables, and differences from zoxide
• TROUBLESHOOTING.md: errors and failures, including the exit-code table, symptom lookup, stderr message reference, and corrupt-database recovery
• BENCHMARKS.md: million-row benchmark against upstream (judge = the real upstream binary)
• Skill-loading agents: .agents/skills/jumbit/SKILL.md

License

MIT License. A semantic rewrite based on zoxide (MIT); the license file carries the original copyright notice