compozsh.

A composable, native Zsh environment

Your terminal.
Composed
for you.

Useful context. Effortless discovery. A place for everything, including the way you work.

Make it yours Read the docs

Native Zsh 5.9+ macOS-first Open source

compozsh — zshNATIVE
ENTRY~/ + Tab
Compozsh / Directory browser3 matches

~ · child directories · hidden off

↑↓ move↵ previewEsc clear1–5 with empty input

In Zsh: → enters a folder; ← goes back; Enter inserts its path.
Native Zsh · composed for you.

Start with a place. Follow your intent.

Type a path and press Tab. Browse children, use Ctrl-O for a shallow preview, or Ctrl-F to search below the displayed folder.

Feature guide

TRY IT ↑ Browser demo · sample data · previews only.

Stock macOS.Zero runtime packages.Full-screen workspaces.Private add-ons stay yours.

01 / The everyday, considered

Find it. Pick it.
Keep going.

One familiar interaction, wherever the next step takes you.

01

A place, a search, a next step.

Open ~/, ./ or another path with Tab. Ctrl-F searches beneath the displayed folder. Select a file, then choose Open, Reveal in Finder, Copy or Insert. Option-Tab brings your recent folders into the same workspace.

TabbrowseCtrl-Fsearch↵choose an action
Understand search sources
02

Remember just enough.

Find a command by the fragments you remember, in any order. History search returns it to your editable prompt, ready for you to review and run.

Ctrl+Ryour history, within reach
03

Review every change in context.

Open a read-only, two-pane Git workspace. Move through changed files on the left and read focused, syntax-aware diffs on the right. Refresh the captured snapshot as AI or editor work evolves.

gbranchesCtrl-XreviewCtrl-Rrefresh
Explore Git review
And the small things that add up.
Read as you type
Live syntax highlighting separates commands, paths, arguments, and operators.
Keep a useful thought
History autosuggestions let you accept a character, a word, or the whole suggestion.
Make reference readable
Colored manual pages and supported command output follow a consistent palette.
Handle the sharp edges
git-discard-all previews repository-wide changes and asks before discarding them.
Explore every feature

One shared interaction

Room to focus.
A clear way back.

Files, branches, history, help and Git review share a full-screen grammar: a clear title, one primary task, visible focus and quiet secondary context. The layout adapts to your terminal, and transitions preserve your place.

Arrows follow spatial disclosure. Enter applies the action shown. Escape goes back. Ctrl-K reveals the available keys. Closing restores your terminal; inserted paths stay visible for review.

Explore the shared controls

02 / A place for your way of working

The defaults are ours.
The shell is yours.

Keep the shared configuration clean. Keep your machine setup private. Compose the rest from small, focused files.

Build your first add-on
YOUR CONFIGURATIONONE SMALL BOOTSTRAP
~/.zshrcFinds and loads your configuration
1Machine setupPRIVATE
~/.zsh.addons/local/init.zsh

Optional. Loads first. Sets up PATH and early tool hooks.

2Independent add-onsANY ORDER
Shared · in the repository.zsh.prompt
.zsh.editor
.zsh.find
…
Private · in your home.zsh.work
.zsh.postgres
.zsh.your-idea
…

One naming convention. Shared and private files load as peers.

A file is the feature. Name it .zsh.something inside your add-on directory. Rename it to break that prefix, or remove it, to disable it.

03 / Make yourself at home

Your setup.
On your terms.

The installer shows its plan, backs up what it replaces, and leaves your private configuration intact.

REQUIRES

macOS · Zsh 5.9+ · Git

Check your environment ↗
01

Give it a home.

Clone once into a stable location. Already cloned? Set repo_dir to that folder instead.

repo_dir="$HOME/Projects/compozsh"
git clone https://github.com/bitbemol/compozsh.git "$repo_dir"
02

Look before you link.

A dry run previews the plan and leaves your files unchanged.

zsh "$repo_dir/install.zsh" --symlink --dry-run
03

Make it yours.

Run the installer, review the plan, and confirm. After it succeeds, start a fresh shell.

zsh "$repo_dir/install.zsh" --symlink
exec zsh

Already have a .zshrc?

Keep it as it is. The installer archives the active file before replacing it. Move your personal setup into the private initializer or focused add-ons.

Full installation and recovery guide
Enable recent-folder access.

In Terminal → Settings → Profiles → your profile → Keyboard, enable Use Option as Meta key. This lets Option-Tab open Recents. Primary in-view actions use Control keys.

Keyboard setup
Updating from 1.x?

Path + Tab and Option-Tab replace f and d. Reload with exec zsh after updating. Personal add-ons remain in your private configuration space.

Migration guide
Prefer a copy instead of a symlink?

Replace --symlink with --copy in the preview and install commands. Copy mode keeps a managed snapshot; rerun the copy installer after updates. In symlink mode, shared changes arrive with a Git pull. Your private files stay separate in either mode.

Small pieces. One coherent experience.

Open the source.
Make it your own.

Explore on GitHub See what’s new