💚 Support Dirgo If Dirgo saves you time, star it on GitHub, share feedback, or contribute a fix. Support development with BTC or USDT TRC20 →

Dirgo

Go anywhere. Instantly.

A fast, local-first directory navigator and command companion for the terminal.

Install · Quick start · Picker · Commands · Configuration · Support · Security · Roadmap

Dirgo indexes your filesystem, finds directories you have never visited, and uses local history to improve ranking over time.

_{Type a fragment. See live matches. Press Enter. You are there.}

Everything Dirgo does

Find and enter any directory

Search the indexed filesystem by a fragment instead of remembering a full path. Dirgo can discover directories you have never visited; local history improves ranking over time without becoming the only source of results.

dgo punk          # jump by directory name
dgo . api         # search below the current directory
dgo repo web      # search project roots
dgo recent        # browse navigation history

Exact paths, bookmarks, and clear matches resolve immediately. Close or ambiguous matches open the picker instead of sending you to the wrong project. This conservative default is designed to work without spending time tuning aggressive jump heuristics.

Choose safely in the terminal

The responsive picker streams candidates, filters while you type, previews directory contents, and restores the terminal cleanly when it closes.

• Ctrl-J / Ctrl-K or arrow keys move the selection.
• Enter navigates; Esc or Ctrl-C cancels.
• Tab toggles the directory preview.
• Ctrl-O, Ctrl-Y, and Ctrl-E open, copy, or launch the configured editor.
• NO_COLOR=1, --no-unicode, and TERM=dumb provide compatible fallbacks.

Remember the places that matter

Bookmarks, recents, project roots, and per-shell back/forward history cover both repeat navigation and discovery:

dgo +work         # bookmark the current directory
dgo @work         # jump to it
dgo back          # move back in this shell session
dgo forward       # move forward again

Act on a result without unsafe shell text

Action flags can appear before or after the query. Dirgo passes paths as data, never as executable shell fragments.

dgo --open                    # open the current directory
dgo --open "/full/path/to/folder"
dgo --open "$HOME\Project"   # PowerShell / Windows
dgo --finder "project name"
dgo "project name" --finder
dgo api --open
dgo api --code
dgo api --copy
dgo api --print

The interactive dgo picker also accepts an existing absolute or relative directory path, even when that directory is not in Dirgo's index.

Complete commands while you type

Local, opt-in suggestions combine directories, filesystem entries, executables, known subcommands and options, navigation history, and optional filtered command history. Selection inserts text only; Dirgo never submits or executes it.

dgo suggestions enable

• Zsh: responsive paged panel with descriptions and Tab insertion.
• PowerShell 7.4.x: native PSReadLine ListView prediction.
• Fish and Bash 4+: enriched native Tab completion.
• Every supported shell: Ctrl+F inserts the best result and Shift+Tab opens the explicit source-labelled picker.

Command history remains off until separately enabled. Likely credentials and unsafe terminal text are rejected before storage. Private tools can be described with bounded, data-only TOML metadata; Dirgo does not run the tool or its completion scripts while you type.

New in 0.5 · commands from the current project

Dirgo now adds commands declared by the project you are inside and marks them as PROJ. It understands:

• npm, pnpm, Yarn, and Bun scripts from package.json;
• Cargo workspace packages, binaries, examples, and features;
• simple Make targets, Just recipes, and Docker Compose services.

_{Real Zsh session · several scenes · every Tab inserts text and runs nothing.}

Manifest files are parsed as bounded data in a background refresh. Dirgo never invokes a package manager, Cargo, Make, Just, Docker, or a completion script to build this list. The private cache is atomic, isolated per project, and capped at 64 projects.

New in 0.6 · Context Engine

When command history is explicitly enabled, Dirgo learns from completed commands locally. It keeps projects separate, prefers commands that worked in the current project and directory, and treats imported 0.5 history as neutral when outcome information is unavailable.

dgo suggestions history enable
dgo suggestions history status
dgo suggestions history list --project .
dgo suggestions history inspect 42
dgo suggestions history export --project . --output ./dirgo-history.jsonl

Commands containing likely credentials or a shell-native leading-space privacy marker are not recorded at all. Exports omit cwd and project paths unless --include-paths is supplied, refuse symlink destinations, and require --force to replace a file. Before intentionally downgrading to Dirgo 0.5, export or clear the opt-in history because 0.5 does not understand schema v2.

Stay local and in control

Dirgo has no account, cloud service, telemetry, or network request during normal navigation. Its index is local, bounded, rebuildable, and published atomically. Shell integration is previewed before installation, backed up, and removable.

One dgo binary; no runtime dependency on fd, fzf, zoxide, or eza.

Install

Homebrew · macOS

Homebrew is a first-class install and update path:

brew install rudysource/tap/dirgo
dgo setup

Release installer · macOS and Linux

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/RudySource/Dirgo/releases/latest/download/dirgo-installer.sh | sh

The installer detects the platform, verifies SHA-256, installs to ~/.local/bin, then asks before connecting the shell.

PowerShell installer · Windows

irm https://github.com/RudySource/Dirgo/releases/latest/download/dirgo-installer.ps1 | iex

The installer verifies SHA-256, installs dgo.exe with its predictor, and asks before changing the user PATH. Open PowerShell 7+ and run dgo setup.

Scoop · Windows

scoop bucket add rudysource https://github.com/RudySource/scoop-bucket
scoop install rudysource/dirgo

Windows support targets PowerShell 7+ and Windows Terminal. Legacy Windows PowerShell 5.1 and cmd.exe are not supported.

Connect your shell

dgo setup previews one managed block for Zsh, Bash, Fish, or PowerShell. On approval it creates a timestamped backup and updates the profile atomically.

dgo setup --dry-run     # preview only
dgo setup               # connect or repair
dgo setup --remove      # remove only Dirgo's managed block

It never uses sudo or silently edits a non-interactive shell. Automation must opt in with dgo setup --yes.

# Linux
sha256sum --check SHA256SUMS

# macOS
shasum -a 256 -c SHA256SUMS

git clone https://github.com/RudySource/Dirgo.git
cd Dirgo
cargo build --release --locked
install -m 755 target/release/dgo ~/.local/bin/dgo
dgo setup

Quick start

dgo refresh       # index your configured roots
dgo punk          # jump by directory name
dgo               # browse everything
dgo . api         # search only below the current directory
dgo ? api         # always ask when names collide

dgo +work         # bookmark the current directory
dgo @work         # jump to the bookmark
dgo repo punk     # search project roots
dgo recent        # browse Dirgo history
dgo back          # move back in this shell session

The first search creates the index. Run dgo refresh after filesystem changes.

Commands

dgo [QUERY]...                  resolve or choose a directory
dgo setup                      connect or repair shell integration
dgo refresh                    rebuild the filesystem index
dgo query <QUERY> [--json]     resolve without navigating
dgo explain <QUERY>            show candidates and score components
dgo root                       print the nearest project root
dgo repo [QUERY]               search indexed project roots
dgo recent [QUERY]             search Dirgo navigation history
dgo back | forward             navigate this shell session
dgo bookmarks                  list bookmarks
dgo bookmark add NAME          create or repair a bookmark
dgo bookmark rename OLD NEW    rename a bookmark
dgo bookmark remove NAME       remove a bookmark
dgo import zoxide              import validated local zoxide scores
dgo config path | show         inspect configuration
dgo doctor                     diagnose the installation
dgo stats                      show local index statistics
dgo support                    show support and security guidance
dgo suggestions enable         enable local shell suggestions
dgo suggestions status         inspect suggestion privacy settings
dgo suggestions history enable opt in to filtered command history
dgo suggestions history status inspect schema and local row counts
dgo suggestions history list   list current-project command aggregates
dgo suggestions history inspect EVENT_ID inspect one completed command
dgo suggestions history clear  erase all history, or select a scope
dgo suggestions history export export versioned, path-redacted JSONL
dgo --update                   install the latest stable release
dgo update-notifications off   disable new-version notices
dgo update-notifications on    enable new-version notices

Run dgo --help or dgo <command> --help for the complete interface.

Configuration

Dirgo reads ${XDG_CONFIG_HOME:-~/.config}/dirgo/config.toml.

schema_version = 1
roots = ["~/Developer", "~/Projects"]

ignore = [".git", "node_modules", "Library", ".cache", "target", "dist"]
respect_gitignore = true
follow_symlinks = false

[ranking]
frequency = 1.0
recency = 0.85
proximity = 0.55
bookmarks = 1.25
projects = 0.30

[ui]
preview = true
accent = "cyan"
icons = "auto"
height_percent = 70

[actions]
editor = "auto"

[suggestions]
enabled = false
command_history = false
live_panel = true
native_completions = true
debounce_ms = 30
native_timeout_ms = 80
max_results = 8
retention_entries = 10000
retention_days = 180
deny_patterns = []

The rebuildable index lives below XDG_CACHE_HOME; bookmarks and history stay below XDG_STATE_HOME. Persistent state is bounded and pruned.

Interactive picker

Platform support

WSL uses its Zsh, Bash, or Fish adapter.

Performance

Apple Silicon macOS, optimized build, three-sample PTY run:

¹ Reproducible local measurements, not universal guarantees. The 1M release budget is 100 ms for both metrics. Run dgo bench --query punk --samples 5 against your own index.

Privacy and security

• No telemetry, analytics, account, cloud sync, or network call during normal use.
• Suggestions and command-history collection are independently disabled by default.
• Context history stays local, project-scoped, bounded, and inspectable; likely secrets are never stored.
• History exports omit filesystem paths by default and never overwrite without --force.
• Paths cross the shell boundary as data, not executable shell text.
• Human-facing output escapes terminal controls and bidirectional overrides.
• Index publication is atomic; recovery preserves corrupted and unknown data.

[!WARNING] The local index contains filesystem paths. Remove personal paths from logs and screenshots.

Report vulnerabilities privately through SECURITY.md.

Release status and roadmap

The 0.6 release is published only after the cross-platform release gate, installer/package inspection, and final documentation review pass. Later features stay proposals until they have an implementation, regression coverage, and a real user-facing demo.

Support Dirgo

Dirgo is free and open source. Voluntary donations help fund maintenance, release infrastructure, platform support, and future improvements.

bc1qk9n84av9f8lj6xcg6sknq2h6r6r495y226zqje

TLuVmVQ1XuYYUWc4bu1AYmJt5a8vTRDNbY

[!IMPORTANT] Verify the complete address and network before sending. Cryptocurrency transfers are irreversible. Donations are voluntary and do not purchase priority support, roadmap influence, or service guarantees.

You can also star the repository, report a focused issue, or contribute.

Troubleshooting

For environment-safe support information, run dgo support or read SUPPORT.md.

Contributing

cargo build --locked
cargo test --all-features --locked

See CONTRIBUTING.md for development checks and pull-request expectations.

License

Dirgo is available under the MIT license or Apache License 2.0.