Help becomes a workspace.
Arguments on the left. Their explanation on the right. Shared colors bring structure to both panes, while the tool description stays in view.
Topics → Explanation → Compose example
Explore Help → ComposeA composable, native Zsh environment
Your terminal.
Composed
for you.
A prompt that responds as you type. Help that opens into an editable draft. Changes you can explore, folder by folder. One native workspace, with room to think.
Native Zsh 5.9+ macOS-first Open source
compozsh — zshNATIVE
CHANGEcd ~/Projects/example-app
╭─ CONTEXT · entered projectOption-I pin
│ PROJECTexample-app
│ PATH~/Projects/example-app
│ GITmain ✓ · tracks origin/main
│ TOOLCHAINswift 6.4 · swiftpm
│ SESSIONuser@host · zsh 5.9
╰─ ❯
╭─ READYOption-Return inspect draft
│ PROJECTexample-app
│ PATH~/Projects/example-app
│ GITmain !2 ?1
│ TOOLCHAINswift 6.4 · swiftpm
╰─ ❯
14:26 › swift test --filter ParserTests
Test Suite ‘ParserTests’ passed.
✓ 2.9s
Directory browserCOMPOZSH
3 matches
~ · child directories · hidden off
↵ previewEsc cancel↑/↓ moveOption-1–5 with empty input
Working changesREAD ONLY
2 unstaged · 1 new · fixed snapshot
All files · Repository · captured sample
FILES3
FOCUSED DIFFREAD ONLY
↵ read / fold↑/↓ move
Fixed simulation · local-only examples
Fixed simulation: entering a project opens its captured context.
How to read the prompt
LITERAL DRAFT
TEXT repeats bounded pieces; flow, control and redirect rows summarize visible structure.
CAPTURED FACT
Context and local manual summaries were captured before editing.
INTENT
Inferred ACTION uses qualifiers. Help-derived ACTION names documented intent. Neither validates a command.
User-selected fixed examples. This page never observes your command line, filesystem, Git state, environment or network.
Arrive somewhere meaningful. See the whole situation.
The Context lens brings captured project, path, Git and toolchain facts into one prompt. Choose a fixed example to explore how it changes while editing.
Feature guideTRY IT ↑ Browser demo · fixed synthetic data · user controlled.
Stock macOS.Zero runtime packages.Full-screen workspaces.Local processing. Compozsh never transmits your data.
Follow the thought through
Understand. Compose.
Keep your place.
Small, connected interactions that keep the next step visible—and yours to choose.
See the draft take shape.
Edit literal fields and inspect the quoted command as it changes. Replace draft closes the workspace and returns you to editing. You decide when to run it.
Fields → Draft → Ordinary prompt
Available for Git review and mkcd. Option-Return needs Option as Meta in Terminal.
A map of the work.
The change atlas groups captured Git entries by folder. Open a file, read its diff, and return to the same review position. Bars count entries, not lines.
Folders → Files → Diff → Back
Explore the change atlasAll examples above are browser simulations. They use bounded sample data, never execute a command, and never discover files or repositories on your machine. The living prompt reacts to editing; data capture follows each tool’s documented scope.
01 / The everyday, considered
Find it. Pick it.
Keep going.
One familiar interaction, wherever the next step takes you.
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 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
Review every change in context.
Start in All files, with clear change states beside each filename. Choose Tree to expand folders and read their captured change summaries. Selecting a file opens its focused, syntax-aware diff. Both views retain your filters and reading position; Working changes refreshes locally.
g --reviewopen reviewCtrl-XviewsCtrl-]filter/exclude
Explore Git review And the small things that add up.
- Read as you type
- Live syntax highlighting separates commands, paths, arguments, and operators.
- Know the intent
- Local manual summaries explain ordinary commands. Compozsh help describes recognized tool operations, and unchanged stock aliases keep their own explanations.
- Keep version context
- READY retains captured toolchain facts between commands. Pin warnings show requested and installed versions: red for older, amber for newer or unverified. Direction alone does not guarantee compatibility.
- One active prompt
- Accepted input leaves a compact timestamped receipt, including empty or spaces-only submissions. The full frame belongs to the prompt you are editing.
- 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 share a palette adapted to the terminal background.
- Handle the sharp edges
g --discard-allpreviews repository-wide changes and asks before discarding them.
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. Selected paths and pane titles stay readable as focus moves. The layout adapts to your terminal, and transitions preserve your place.
Arrows follow spatial disclosure. Enter applies the action shown. Escape goes back. Ctrl-] switches between filtering and exclusion where available. The last shortcut, Ctrl-K, opens all applicable keys, with distinct colors for labels, descriptions and notes. Press it again to return to your place. Closing restores your terminal; inserted paths stay visible for review.
Explore the shared controls02 / 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-onYOUR CONFIGURATIONONE SMALL BOOTSTRAP
~/.zshrcFinds and loads your configuration1Machine setupPRIVATE
~/.zsh.addons/local/init.zshOptional. 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.
The math behind the idea
The algebra of
a composed shell.
Small, independent pieces give us three useful laws. Here, ⊕ means combining peer configuration, and ≈ means equivalent configured behavior.
Commutativity
Change the order. Loading the same peers in a different order gives you the same configured behavior.
Associativity
Change the grouping. Organize peers into folders that make sense to you. Grouping adds no loading phase.
Idempotence
Load it again. Re-sourcing an unchanged peer preserves its setup without stacking duplicate hooks or registrations.
Same pieces. Same result.
INTERACTIVE MODELLoading order
A → B → C
Configured peers · 3
A · B · C
Composition combines pieces into a workflow; its steps can depend on order. These laws govern peer setup under the same prerequisites and ownership rules, with capabilities checked at invocation. Compare behavior after loading finishes. The optional initializer still loads first and sits outside these laws. Runtime operations keep their sequence: capture candidates, then filter, then act. Regression tests check the shell contract; this model illustrates it.
Read the loading contractA 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.
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-run03
Make it yours.
Run the installer, review the plan, and confirm. After it succeeds, start a fresh shell.
zsh "$repo_dir/install.zsh" --symlinkexec zshAlready 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 guideEnable Option shortcuts.
In Terminal → Settings → Profiles → your profile → Keyboard, enable Use Option as Meta key. Option-I pins the Context lens, Option-Tab opens Recents, and Option-Return inspects the current draft. Automatic lens changes and primary in-view actions need no Option setting.
Keyboard setupUpdating 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.
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.