Compozsh 2.0.0 — One Filesystem Workspace

Compozsh 2.0 brings browsing, recent folders, scoped search, and file actions together in one responsive filesystem workspace.

Start from a place

• Type ~/, ./, /, or another directory path and press Tab to browse.
• Press Option-Tab at the prompt to recall recently visited folders.
• Press Ctrl-F inside the workspace to search beneath the displayed folder.
• Select a file to open its contextual actions: Open with default app, Reveal in Finder, Copy path, or Insert path.

Directory selection returns a quoted, editable path to the prompt. Review it and press Enter to change directory.

Clearer search

Search defaults to Git inside repositories, Spotlight at home/root on macOS, and bounded filesystem discovery elsewhere.

The workspace displays its source, scope, and “Searching…” status before capture. Source failures are reported explicitly. Filtering captured results stays separate from discovery.

A cohesive full-screen experience

• Shared layouts across filesystem navigation, Git branches, history, and tool help.
• Dedicated titles and input rows, primary result lists, and responsive detail panels.
• Scrolling through additional results with visible-number selection.
• Restored filters and selections when navigating back.
• Continuous screen transitions and improved resize cleanup.
• Consistent Control shortcuts and a contextual Ctrl-K keyboard guide.

cpdir also highlights the displayed path while keeping clipboard contents plain.

Migrating from 1.x

This release removes d and f:

• Replace d with Option-Tab; use native dirs -v for a textual stack.
• Replace f with path + Tab → Ctrl-F.
• Replace scripting uses of f --list and f --print0 with native find, git ls-files, or mdfind.
• g remains the dedicated Git branch workspace.

Enable Use Option as Meta key in your Terminal profile for Option-Tab.

For symlink installations, pull the repository and run exec zsh. Copy installations must also rerun the copy installer. Personal configuration remains separate; update any private aliases that referenced retired commands.

Documentation and verification

The website now demonstrates Browse, Recents, scoped search, and file actions with safe interactive examples. README and contributor guidance document the new workflow.

Verified with 157 native shell tests, 7 website tests, and responsive browser checks.

Still built with native Zsh 5.9 and macOS tools, with no new runtime dependencies.

Full changelog: 1.2.0...2.0.0

Compozsh 1.2.0 — Clearer Help, Interactive Showcase

Compozsh 1.2.0 makes its tools easier to learn, with comprehensive command guides, semantic help colors, and a new interactive website.

Clearer command help

• Expanded every shipped Compozsh command’s --help with relevant defaults, examples, prerequisites, controls, and safety boundaries.
• Clarified how f chooses its search scope, how fuzzy matching works, and why traversal limits or Spotlight indexing can affect results.
• Documented directory and branch picker sources, selection behavior, clipboard actions, and fallbacks.
• Expanded installation guidance for symlink and copy modes, updates, private configuration, and recovery.
• Kept direct command help and the compozsh tool explorer connected to the same documentation.

Semantic help colors

• Added consistent emphasis for headings, options, examples, and safety information through the shared output palette.
• Preserved identical plain text in pipes, redirects, command substitutions, and unsupported terminals.
• Respected NO_COLOR and retained plain help when the output add-on is disabled.
• Kept help rendering free of external commands and documentation evaluation.

Interactive website

Explore the Compozsh website through five task-focused demonstrations: Context, History, Files, Navigate, and Tools.

The site includes searchable sample pickers, architecture explanations, and installation guidance. Demonstrations use synthetic data and run entirely in the browser.

Quality and compatibility

• Expanded the native Zsh suite from 78 to 86 passing tests.
• Added terminal-based coverage for help colors, exact plain-text fallbacks, and safe palette handling.
• Preserved independently loadable, order-independent add-ons.
• No breaking changes or new shell runtime dependencies.

Updating

From your Compozsh clone, run git pull --ff-only.

For a copied installation, also run zsh install.zsh --copy. After updating, open a new terminal or run exec zsh.

Your private initializer and personal add-ons remain separate from the shared configuration.

Full changelog: 1.1.0...1.2.0

Compozsh 1.1.0 — Fuzzy Discovery and Navigation

Highlights

Compozsh now brings its fuzzy, interactive interface to tool discovery, file search, and directory navigation—while remaining native Zsh with no plugins, package managers, or external runtime dependencies.

Added

• Added hierarchical fuzzy directory completion with interactive drill-down.
• Added f, a bounded fuzzy finder for files and directories with project, current-directory, custom-root, home, and global Spotlight scopes.
• Added compozsh, a live tool explorer that automatically discovers public commands from loaded add-ons.
• Added consistent, side-effect-free --help documentation to every shipped public Compozsh command.
• Added cpdir to copy the exact current working directory to the macOS clipboard.
• Added semantic native output colors for Git, grep, and man.

Tool discovery

Run the new interactive explorer:

compozsh

Every loaded public add-on command appears automatically. Search fuzzily, select a command, and view its documentation without executing it.

Noninteractive forms are also available:

compozsh --list
compozsh help f

The catalog is regenerated from live Zsh function metadata. It requires no registry, cache, loading order, or manual registration, and it automatically includes compatible user-defined add-on commands.

File discovery

Search interactively from the current Git project or directory:

f query

Additional scopes and machine-readable output are available through:

f --help

Results are bounded, safely shell-quoted, and never opened or executed implicitly.

Architecture and quality

• Preserved independent, order-agnostic add-on loading.
• Centralized help providers so direct and explorer documentation cannot drift.
• Kept help inspection free of filesystem writes, navigation, prompts, network access, and optional-tool detection.
• Clarified picker cursor and file-type glyphs in the documentation.
• Expanded the native Zsh test suite from 52 to 78 passing tests.
• Added regression coverage for discovery, help safety, fuzzy search, output colors, navigation, and clipboard behavior.

Updating

For the recommended symlink installation:

git -C "$repo_dir" pull --ff-only
exec zsh

For a copied installation:

git -C "$repo_dir" pull --ff-only
zsh "$repo_dir/install.zsh" --copy
exec zsh

Compozsh 1.0.1 — Branch Picker Reliability

Fixed

• Fixed the g branch picker incorrectly reporting that local branches could
  not be inspected when some branches were absent from the recent checkout
  reflog.
• Added regression coverage for repositories containing local branches that
  have never been checked out recently.

Verification

• 52 native Zsh tests passing.
• Syntax and diff checks passing.
• Fix confirmed on a second macOS machine.

Updating

git pull --ff-only
exec zsh

Compozsh 1.0.0 — Compose your shell, natively

Compozsh 1.0.0 is the first public release of a polished, composable Zsh environment built entirely with native Zsh 5.9—no plugin manager, third-party shell code, patched fonts, background daemons, or persistent feature caches.

Highlights

• Responsive prompt with Git state, runtimes, toolchains, virtual environments, jobs, and project context
• Live command-line syntax highlighting and history autosuggestions
• Ranked fuzzy Ctrl-R history search
• Interactive directory and Git branch pickers
• Native completion and macOS-friendly key bindings
• Safe git-discard-all workflow
• Terminal-aware colors for listings, searches, and manual pages
• Optional Xcode skill export for supported coding agents
• Tiny .zshrc bootstrap with recursively discovered, order-independent .zsh.<name> units
• Private machine configuration cleanly separated from shared immutable behavior
• Safe installer with dry runs, recovery backups, validation, and transactional rollback
• 51 dependency-free native Zsh tests

Install

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

zsh "$HOME/Projects/compozsh/install.zsh" --symlink --dry-run
zsh "$HOME/Projects/compozsh/install.zsh" --symlink

exec zsh

Compozsh requires Zsh 5.9 or newer and is distributed under GPL-3.0-or-later.

Simple mechanisms, focused units, user-owned configuration, and no hidden machinery.