Introduction

Lacy is a magical cd alternative that makes navigating much more efficient!

Why?

Have you ever been annoyed after mistyping a directory name with the cd command, or found cd autocomplete tedious when you have many similarly named directories?

Lacy solves this by improving the cd functionality in smart ways, but keeping it as simple as cd - if you know cd, you know lacy!

But lacy also adds new features to make navigating in the terminal easier and faster!

Interested yet? Check out all of lacy's features or just try it out!

Features

To use lacy, you use the y command. (You can easily change the default key, see FAQ)

Improved CD Features

Lacy is cd compatible, meaning everything you can do with cd, you can do it the exact same way in lacy:

cd Desktop/foo/bar
y Desktop/foo/bar

cd /Users/tiimo
y /Users/tiimo

cd ~
y ~

But where cd is very strict about what you type, lacy isn't:

cd Desktop/foo/bar
y dskt/fooo/bar

cd /Users/tiimo
y / usrs/timoo

You can even write spaces instead of slashes if you want:

cd Desktop/foo/bar
y dskt fooo bar

cd /Users/tiimo
y / usrs  timoo

Lacy uses a custom fuzzy matching algorithm, specifically crafted for lazily writing paths so you always find what you want!

Navigating back using .. is also a feature that is improved.

cd ../..
y ../..

Instead of writing ../.. for each level, you can just type ... (Some shells already have this functionality built in).

cd ../../..
y ....

This feature is currently WIP!

cd -1
y -1

New Lacy Features

Skipping Directories

If you ever know your target directory, but forgot whats between it, you can just skip it using -.

cd Desktop/foo/bar
y - foo bar

You can do that as many times as you want.

cd Desktop/foo/bar
y - - - foo bar

Multiple Results

By now you probably have wondered what happens if lacy can't decide what your target folder is and finds multiple results.

In that case, lacy opens a multiselect window where you can select your target

? Multiple possibilities found! ›
❯ /Users/tiimo/Desktop/projects/lacy/devtools
  /Users/tiimo/Desktop/projects/lacy/docs
  /Users/tiimo/Desktop/projects/lacy/result
  /Users/tiimo/Desktop/projects/lacy/src

If you want, you can easily swap out the default select with your own solution, like for example fzf.

Frequently Asked Questions

For other questions, see bottom on how to contact me.

General Questions

Why not use cd + autocomplete?

Autocomplete is great, but sometimes it can get annoying with lots of similar named folders.

cwd/
  folder_ab/ <-- Target
  folder_ba/ 
  folder_ac/
  ab_folder/

In this scenario, you'd have to press tab multiple times and see what was autocompleted. With lacy, you can just type y foab.

In some cases, autocomplete is still useful. Lacy still offers that autocomplete.

Why not use Z (zoxide or similar tools)?

These tools are great and a great inspiration for lacy, but the goal of lacy is to have a tool that you can use from the first second and in unknown environments, which e.g. Zoxide doesn't, as it first has to learn your behavior.

Technical Questions

Can I change the default lacy key?

Default is y, but you can easily change it by modifying the lacy init shell command. You can change it by passing the --cmd option, e.g. lacy init zsh --cmd c sets it to c.

See shell options for all available options.

Can I use my own selector instead of the built in one?

Yes! For example, you may want to use fzf. You can easily do that by passing the --custom-fuzzy option to lacy init shell, e.g. lacy init zsh --custom-fuzzy fzf.

See shell options for all available options.

Why does it need a shell script?

It is needed because you can't change the directory without using cd. So the shell script just executes cd if needed.

How can I use both Lacy and `z`/`zoxide`?

If you have cd aliased to z, then it should work as long as the Lacy shell eval is below the z eval. If not, run lacy init <shell> and manually add the result to your shell config. Then, replace the cd's with z.

Install

After installation, don't forget to do setup!

Cargo (Universal)

cargo install lacy

Homebrew (macOS/Linux)

brew install timothebot/tap/lacy

NixOS ❄️

There are a couple of ways to get lacy up and running on your Nix system. Both methods require adding lacy to your flake.nix inputs.

# flake.nix
{
  inputs = {
    lacy.url = "github:timothebot/lacy";
    # ... other inputs
  };

  outputs = { self, nixpkgs, lacy, ... }@inputs: {
    # ...
  };
}

1. Home Manager Module (Recommended)

This is the easiest way to manage lacy if you're using Home Manager. The module handles most of the setup for you. You must explicitly add the lacy flake as an overlay to your configuration to ensure the lacy package is available.

# home.nix
{ pkgs, inputs, ... }: {
  # Explicitly add the overlay to make lacy visible in your pkgs set
  nixpkgs.overlays = [ inputs.lacy.overlays.default ];

  imports = [
    inputs.lacy.homeManagerModules.default
  ];

  programs.lacy.enable = true;
}

2. Nix Overlay (NixOS / Home Manager)

If you prefer to manage packages directly without using the Home Manager module, this is the way to go. You apply the overlay and then add the lacy package to your system or user packages.

For NixOS

# In your NixOS configuration (e.g., /etc/nixos/configuration.nix)
{ pkgs, inputs, ... }: {
  nixpkgs.overlays = [ inputs.lacy.overlays.default ];

  environment.systemPackages = [ pkgs.lacy ];
}

For Home Manager

# In your home-manager configuration (e.g., ~/.config/nixpkgs/home.nix)
{ pkgs, inputs, ... }: {
  nixpkgs.overlays = [ inputs.lacy.overlays.default ];

  home.packages = [ pkgs.lacy ];
}

3. Run `lacy` directly

Just want to try it out? You can run lacy from the command line without adding it to your system configuration.

nix run github:timothebot/lacy

Set Up

After you installed lacy, you have to add it's shell configuration to your shell.

Shell Setup

For more shell options, see lacy init --help.

Zsh

# ~/.zshrc
eval "$(lacy init zsh)"

Bash

# ~/.bashrc
eval "$(lacy init bash)"

Fish

# ~/.config/fish/config.fish
lacy init fish | source

Other shells

Feel free to contribute the init script for your preferred shell.

Shell Options

You can customize the shell script that gets generated by using these options:

Option	Default	Description
`--cd-cmd`	`cd`	Define the command to be used instead of `cd`. (e.g. `z`)
`--cmd`	`y`	The name of the main lacy command you use for navigating.
`--custom-fuzzy`	none	Configure this to disable lacy's built in UI selector and replace it with your own command. (e.g. `fzf`)

Lacy Documentation