cdd

A TUI that lets you jump to recent Projects.

Demo

Install

GitHub Releases

Download a prebuilt binary from the Releases page. Archives are published as tar.gz for linux and darwin, each in amd64 and arm64. Verify a download against the release's checksums.txt:

sha256sum --check --ignore-missing checksums.txt

Then extract the archive and put the cdd binary on your PATH.

go install

go install github.com/kryft-dev/cdd/cmd/cdd@latest

Shell setup

cdd needs a shell Wrapper so choosing a Project in the Picker can actually Jump your shell there — a subprocess cannot change its parent shell's working directory on its own.

fish — add to ~/.config/fish/config.fish:

cdd init fish | source

bash — add to ~/.bashrc:

eval "$(cdd init bash)"

zsh — add to ~/.zshrc:

eval "$(cdd init zsh)"

First run

Create a config.toml (see Config reference) with at least a root, then seed History with a Scan of everything already under Root:

cdd scan

Usage

cdd            # open the Picker over History, ordered by recency
cdd <query>    # open the Picker pre-filtered by query

Keys

Default key map:

Key	Action
type	filter the list
↑ / ctrl+p	move up
↓ / ctrl+n	move down
enter	Jump to the selected Project
esc / ctrl+c	cancel
ctrl+u	clear the filter

Vim key map (keys.vim = true): the list is focused on open.

Key	Action
j	move down
k	move up
g / G	jump to first / last row
f / /	focus the filter
esc (filter)	return to the list, keeping the query
esc / q	cancel
enter	Jump to the selected Project

Layout

The Picker ships two Layouts, selected with picker.layout.

The Grouped Layout (grouped, the default) groups Projects under Kind headers, marks the selected row with a caret, and puts the filter line above the list.

The List Layout (list) is a flat fzf-style run: no Kind headers, Projects in History order with never-visited ones last, kind/ muted before each Project name, the filter prompt below the list, and a ▌ bar plus a background highlight on the selected row.

Both draw the same preview pane, use the same keys, status glyphs and colours, and degrade the same way on a narrow terminal.

Config reference

cdd reads config.toml from $XDG_CONFIG_HOME/cdd/config.toml, falling back to ~/.config/cdd/config.toml when XDG_CONFIG_HOME is unset.

root = "~/Developer"      # required, no default
exclude = []              # paths relative to Root, glob-matched
include_hidden = false
[history]
max_visits = 1000         # must be >= 1
[keys]
vim = false
[picker]
layout = "grouped"        # or "list" for the flat fzf-style layout

• root (required): the top-level directory whose Kinds are searched for Projects. A leading ~ is expanded to the user's home directory; $VAR is left as-is.
• exclude: paths relative to Root, matched with path.Match semantics, that are skipped when discovering Kinds and Projects.
• include_hidden: when false (the default), hidden directories are excluded at both Kind and Project level.
• [history].max_visits: the maximum number of Visits kept in History. Must be at least 1; defaults to 1000.
• [keys].vim: when true, the Picker opens with the list focused and uses the vim key map described above. Defaults to false, the default key map.
• [picker].layout: which Layout the Picker draws, "grouped" (the default) or "list", as described above. Any other value is a config error.

History is stored at $XDG_DATA_HOME/cdd/history, falling back to ~/.local/share/cdd/history when XDG_DATA_HOME is unset.

How it works

A Scan sweeps Root once and seeds History with a Visit per discovered Project, dated from evidence found inside the Project itself. The Picker lists Projects drawn from History, most recently visited first, and lets you choose one; choosing a Project records a new Visit and hands its path to the Wrapper, which turns it into a Jump in your shell.

Contributing

See CONTRIBUTING.md for development setup, the CONTEXT.md glossary, and the commit and pull request workflow.

License

MIT