Winuxsh

Bash, native on Windows. No WSL. No VM. No /mnt/c. No cmdlet dialect. Just the shell your fingers already know — and the one your AI agent actually speaks.

This is the Winuxsh documentation. Start with the guides, or jump straight into the shell:

C:\Users\you\repo
❯ test -f Cargo.toml && echo "rust, obviously"
rust, obviously

❯ printf "%s\n" alpha beta gamma | grep beta
beta

❯ cd "C:\Program Files"
C:\Program Files

What Winuxsh is

• Bash syntax. if, for, case, $(...), pipes, redirects, heredocs, functions, aliases — the whole grammar, powered by rubash, which passes the GNU Bash project's own test suite (86/86 upstream tests green).
• Windows-native. One binary, one process. Native Windows paths (C:\... and C:/...), direct execution of git.exe, node.exe, cargo.exe, python.exe — no VM, no emulation layer, no path conversion roulette.
• Unix commands included. WinuxCmd ships ls, cat, grep, find, test, printf, and friends as Windows command links, with no separate installation.
• AI-native. winuxsh -c is a contract: no banners, stable stdout/stderr, exact exit-code propagation. What an agent writes is what the process receives — the quoting roulette of PowerShell and the path mangling of MSYS/Git Bash are both gone.
• A prompt you'll enjoy. 27 bundled themes (agnoster, spaceship, pure, catppuccin-mocha, tokyonight, p10 family, ...), a git prompt that grows teeth inside any repository, syntax highlighting, autosuggestions, vi and emacs modes, and Ctrl+R history search.
• Plugins with a permission model. 40+ bundled packs (git, docker, kubectl, npm, zoxide, direnv, fzf, thefuck, ...), with third parties sandboxed in a WASM host behind declared permissions.

The documentation

Get it

Download the installer from GitHub Releases, or build from source:

git clone https://github.com/unixwin/winuxsh.git
cd winuxsh
cargo build --release
target\release\winuxsh.exe

Keep it current with winuxsh --self-update (or self-update inside the shell) and wpm update winuxcmd for the Unix command set. Questions and bug reports go to github.com/unixwin/winuxsh/issues.

Shell semantics live upstream in rubash — fix the engine, and every Bash user on Windows wins.

Why Winuxsh

The long version of the pitch. The README sells it in five seconds; this page shows the receipts.

The Windows shell civil war

Every Windows developer knows the tabs open on their machine:

The treaty

Winuxsh is one native Windows binary that runs Bash syntax on Windows paths with real Windows programs — and brings the Unix commands Windows never had (ls, cat, grep, find, test, printf, ...).

One binary. One process. No distro to patch, no emulation layer to appease.

PowerShell eats arguments

Windows itself is the root cause: the platform has no argv array. Every executable receives a single command-line string and parses it with its own rules — and PowerShell adds a second parser on top. That's how PowerShell/PowerShell#1995 ("Arguments for external executables aren't correctly escaped") became a household name, and how dotnet/runtime#23347 opens by citing "the ongoing quoting woes PowerShell experiences."

Same command line, two shells. Watch what actually reaches the process:

# PowerShell 5.1                                # Winuxsh
> node -e "console.log(JSON.stringify(          ❯ node -e "console.log(JSON.stringify(
    process.argv.slice(1)))" "a b" "" "c\"d"      process.argv.slice(1)))" "a b" "" "c\"d"
    "e\f" "---"                                   "e\f" "---"

ParserError: TerminatorExpectedAtEndOfString   ["a b","","c\"d","e\\f","---"]

That command is written the way any model trained on Bash would write it. PowerShell throws a parse error before the process even starts. And when you quote it PowerShell's own way, the damage is quieter but still real: five arguments in, two mangled ones out — the empty string vanishes, the embedded quote is flattened, the last two arguments fuse into one:

> node -e "console.log(JSON.stringify(process.argv.slice(1)))" "a b" "" 'c"d' "e\f" "---"
["a b","cd e\\f ---"]

Agent casualties, with receipts

For humans this is a nuisance. For AI agents it's a minefield: models are trained on Bash, their quoting instincts are Bash-shaped, and on a PowerShell machine every generated command is a roll of the dice.

• anthropics/claude-code#65162 — agent used a PowerShell here-string (@'...'@) inside the Bash tool; the git commit message was silently corrupted, and git commit still exited 0.
• anthropics/claude-code#83243 — trivial commands fail with unexpected EOF on Windows when PowerShell is the primary shell.
• anthropics/claude-code#76490 — Bash allow-list rules never match Windows drive-letter paths; every run re-prompts.
• openai/codex#31548 — Windows users are voting to make the Codex agent shell configurable; it is locked to PowerShell today.
• openai/codex#35995 — Python works in the interactive shell but silently disappears inside Codex task execution.
• openai/codex#33891 / openai/codex#36560 — the ChatGPT desktop app flashes PowerShell windows while its agent works.
• microsoft/vscode-python-debugger#233 — a space in a path yields incorrectly quoted debug commands.

The path philosophy: native in, native out

Windows-native binaries don't speak the MSYS dialect. Here is Git Bash, in the wild, failing at exactly the things Winuxsh does without thinking:

What just happened, command by command:

MSYS "solves" paths by guessing: it heuristically rewrites /c/foo into C:\foo, and famously mangles innocent arguments along the way — the notorious case of git grep "/pattern" silently becoming git grep "C:\...\pattern" is why MSYS2 still ships MSYS2_ARG_CONV_EXCL as an escape hatch. Every native tool call is a game of path roulette.

Winuxsh is the only Windows shell that doesn't translate anything — because it speaks both dialects itself and hands every process its own native language:

❯ cd /c/Users/you/repo     # MSYS-style input: understood
C:/Users/you/repo            # output: always Windows-native
❯ node -e "console.log(process.cwd())"
C:\Users\you\repo            # native binaries get native cwd
❯ cd "C:\Program Files"     # Windows-style input: understood
❯ pwd
C:/Program Files

Input in any dialect. Output always native. Zero guessing, zero conversion roulette — for your fingers, and for your agent.

Getting Started with Winuxsh

A short walkthrough from zero to a working prompt with git status.

1. Build or download

git clone https://github.com/unixwin/winuxsh.git
cd winuxsh
cargo build --release

After building, the binary is at target\release\winuxsh.exe. You can run it directly, or add target\release to your user PATH using your normal Windows environment settings:

target/release/winuxsh.exe

If you are using the release zip, winuxsh automatically runs the activation script on first start when command links are missing:

winuxsh winuxcmd/activate-winuxcmd.sh

That creates local command links inside winuxcmd/, so ls, cat, and friends resolve normally. Once the links exist, startup skips activation.

2. Start the shell

winuxsh

You should see something like:

user@DESKTOP C:\Users\you
%

Type exit or press Ctrl+D to quit.

3. See the git prompt

cd into any git repository:

cd C:\Users\you\repo
# if inside a repo, the prompt changes:
user@DESKTOP C:\Users\you\repo  git:(main) ●1 ✚2 ?1
%

Symbols at a glance:

The branch name is green when the tree is clean, yellow when dirty.

4. Try some commands

pwd                                  # prints C:/Users/you/repo
ls -la                               # Unix-style listing
echo "hello from $USER"
for i in 1 2 3; do echo $i; done
if [ -f Cargo.toml ]; then echo "yep"; fi
cat Cargo.toml | grep name
grep -n "fn main" src/main.rs

Windows paths work directly:

ls C:\Windows\System32\drivers\etc
ls D:/Projects
cd "C:\Program Files"

Multiline blocks work naturally:

for f in *.toml; do
  echo "found $f"
done

5. Try git completions

git ad<Tab>                # completes to `git add`
git commit -<Tab>           # shows flags: --message, --all, --amend
git push --fo<Tab>          # completes to --force
git branch -<Tab>           # shows -d, -D, -m, -v, -a, -r

6. Set up your config

Create ~/.winuxshrc for interactive shell code, plugin selection, and theme selection:

WINUXSH_THEME=minimal
WINUXSH_THEME_PLUGIN=theme-minimal
WINUXSH_PROMPT_SYMBOL="❯"
export WINUXSH_THEME WINUXSH_THEME_PLUGIN WINUXSH_PROMPT_SYMBOL

WINUXSH_PLUGINS=(prompt-core git)

if [ -z "${HOME:-}" ] && [ -n "${USERPROFILE:-}" ]; then
  HOME="$USERPROFILE"
  export HOME
fi

if [ -z "${WINUXSH:-}" ]; then
  WINUXSH="$HOME/.oh-my-winuxsh"
  export WINUXSH
fi

[ -f "$WINUXSH/oh-my-winuxsh.winux" ] && . "$WINUXSH/oh-my-winuxsh.winux"
winuxsh_prompt_use_template "{cwd} {git_prompt}{prompt_char} " "{time} " 2>/dev/null || true

export EDITOR=vim
alias ll='ls -la'
alias la='ls -a'
alias gst='git status'
alias gco='git checkout'
alias gl='git log --oneline --graph --decorate --all'

hello() {
  echo "hello from winuxsh"
}

~/.winuxshrc is sourced only for the interactive REPL and the -C one-shot REPL command path. It does not run for winuxsh -c ..., script files, or stdin script execution, so agent and CI surfaces stay deterministic.

~/.winshrc is a legacy compatibility fallback and is used only when ~/.winuxshrc is absent. ~/.winshrc.toml remains supported for legacy and managed structured state such as plugin CLI enable/disable records, migration blocks, completion overrides, test isolation, and advanced machine-editable settings. Prefer ~/.winuxshrc for normal interactive customization.

6b. Prompt and theme plugins

Themes are official plugins. To use a Powerlevel-style theme, switch the theme plugin in ~/.winuxshrc:

WINUXSH_THEME=p10-lean
WINUXSH_THEME_PLUGIN=theme-p10-lean
WINUXSH_PLUGINS=(prompt-core git)

Useful bundled theme plugins include theme-minimal, theme-classic, theme-pure, theme-robbyrussell, theme-p10-lean, theme-p10-classic, theme-p10-rainbow, and theme-p10-pure. Theme TOML assets support named colours, 256-colour indexes, and true-colour #RRGGBB foreground/background values plus bold, italic, underline, and dimmed flags.

Prompt templates use the public prompt-core API:

winuxsh_prompt_use_template "{cwd} {git}{prompt_char} " "{status}{time} "

Available template tokens include {cwd}, {cwd_base}, {user_host}, {git}, {git_prompt}, {status}, {time}, {command_execution_time}, {newline}, and {prompt_char}. The Git prompt snapshot is refreshed during startup/precmd so late Git work warms the next prompt instead of redrawing the line the user is typing on.

7. Import your .zshrc (optional)

If you already have a .zshrc with Oh My Zsh, let winuxsh inspect it:

winuxsh --zsh-compat-report
winuxsh --zsh-compat-import-plan

Review the plan. If it looks safe (it scans, does not blindly source):

winuxsh --zsh-compat-import-apply
winuxsh --zsh-compat-doctor

8. Official plugin bundle

Winuxsh has a built-in plugin system. oh-my-winuxsh is the official bundled plugin distribution, not an Oh My Zsh fork and not zsh plugin support. It ships first-party packs such as git, docker, kubectl, npm, zoxide, direnv, dotenv, fzf, prompt presets, and keybinding presets.

The normal interactive shape is the ~/.winuxshrc plugin list shown above. When winuxsh plugin enable/disable or migration tooling needs structured state, it writes managed records to ~/.winshrc.toml, for example:

[plugins]
enabled = true
bundles = ["oh-my-winuxsh"]
load = ["git", "prompts", "keybindings"]

[plugins.git]
enabled = true
permissions = ["shell:source", "cwd:read", "process:run:git"]

[plugins.zoxide]
enabled = false
permissions = ["cwd:read", "process:run:zoxide"]

Existing [zsh.native_plugins] and [zsh.native_widgets] config remains a legacy migration compatibility surface. New machine-managed config should use [plugins], while user-authored interactive startup should use ~/.winuxshrc. Official shell helper packs can ship reviewed bundle-local init.winux source scripts. If ~/.winuxshrc exists, it is the source-plugin entry point and loads the framework directly. Without ~/.winuxshrc, the legacy managed startup path can still load enabled source packs before fallback ~/.winshrc. Use winuxsh plugin list, winuxsh plugin search, winuxsh plugin themes, and winuxsh plugin review for current inventory, theme sources, and permission checks; legacy --zsh-native-packs remains migration-only.

What next

• Zsh Migration Guide for detailed .zshrc import
• Plugin System Direction for the v3 plugin model
• Plugin System Roadmap for the execution sequence
• Oh My Winuxsh Bundle Plan for the official bundle
• Roadmap to see what is planned
• Source at github.com/unixwin/winuxsh

Advanced Winuxsh Usage

This guide covers the surfaces that matter after the first successful launch: execution modes, startup files, prompt/theme plugins, command discovery, and update/debug workflows.

For first-time setup, start with Getting Started.

Execution Modes

Winuxsh has three intentionally different execution paths:

winuxsh                         # interactive REPL
winuxsh -c 'pwd; echo "$SHELL"'  # quiet script/CI command mode
winuxsh -C 'alias ll; pwd'       # one-shot REPL command

• Use the interactive REPL for normal shell work.
• Use -c for scripts, tests, CI, and coding agents. It does not load ~/.winuxshrc, ~/.winshrc, prompt plugins, or interactive lifecycle hooks.
• Use -C only when a one-shot command needs the same startup state as the interactive REPL. It loads ~/.winuxshrc and lifecycle hooks, then exits.

This separation keeps automation deterministic while still allowing a rich interactive shell.

Startup And Config

Use ~/.winuxshrc as the normal human-authored entry point:

WINUXSH_THEME=p10-classic
WINUXSH_THEME_PLUGIN=theme-p10-classic
WINUXSH_PROMPT_SYMBOL=">"
export WINUXSH_THEME WINUXSH_THEME_PLUGIN WINUXSH_PROMPT_SYMBOL

WINUXSH_PLUGINS=(prompt-core git common-aliases path-tools extract)

[ -f "$WINUXSH/oh-my-winuxsh.winux" ] && . "$WINUXSH/oh-my-winuxsh.winux"

alias ll='ls -la'
export EDITOR=vim

The legacy files still exist, but they should not be the primary user path:

• ~/.winshrc is a fallback only when ~/.winuxshrc is absent.
• ~/.winshrc.toml is legacy/managed machine state for plugin CLI records, migration blocks, bundle versions, tests, and advanced overrides.

Do not put automation-critical behavior only in an interactive rc file. Pass needed environment variables directly to winuxsh -c or the script process.

Prompt And Themes

Prompt behavior is plugin-owned. The core shell provides host APIs and lifecycle hooks; official theme and prompt behavior lives in bundled plugins.

Common rc shape:

WINUXSH_THEME=p10-lean
WINUXSH_THEME_PLUGIN=theme-p10-lean
WINUXSH_PLUGINS=(prompt-core git)
export WINUXSH_THEME WINUXSH_THEME_PLUGIN

[ -f "$WINUXSH/oh-my-winuxsh.winux" ] && . "$WINUXSH/oh-my-winuxsh.winux"
winuxsh_prompt_use_template "{cwd} {git_prompt}{prompt_char} " "{status}{time} " 2>/dev/null || true

Theme assets can use named colors, 256-color indexes, and true-color #RRGGBB foreground/background values. Prefer changing the theme plugin or theme asset instead of hardcoding prompt rendering in shell core.

Git Prompt Performance

Git status should be consumed as a coherent prompt snapshot, not rendered by blocking every prompt draw with fresh Git processes. The intended shape is:

• prompt/theme plugins render the latest available snapshot;
• the host keeps git status work warm in the background;
• late git work updates the next prompt instead of repainting the active input line.

If the prompt flickers or repaints the current line, debug the lifecycle and git snapshot path rather than adding more inline Git calls to the theme.

Plugin Workflow

Use the CLI to inspect the active bundle instead of relying on stale docs:

winuxsh plugin list
winuxsh plugin search git
winuxsh plugin themes
winuxsh plugin info git
winuxsh plugin review git
winuxsh plugin doctor

Normal interactive choices belong in ~/.winuxshrc:

WINUXSH_PLUGINS=(prompt-core git docker kubectl zoxide)
WINUXSH_THEME_PLUGIN=theme-p10-rainbow

Use managed plugin CLI operations when you need a reviewable machine record, permissions, bundle update state, or rollback.

Command Discovery And WPM

Winuxsh resolves Unix-style commands through normal Windows PATH. When a command is missing or comes from the wrong provider, inspect the active installation:

command -v winuxsh
command -v winuxcmd.exe
command -v ls
winuxcmd.exe wpm index status
winuxcmd.exe wpm search jq
winuxcmd.exe wpm links rebuild --force

Do not assume /usr/bin exists. Winuxsh is a Windows process using Windows executables and command links.

Windows Paths And Home

Prefer durable Windows paths in scripts:

cd C:/Users/you/repo
ls "C:\Program Files"
cd ~

Prompt display should normally render the home directory as ~ and descendants as ~/path, but internal process paths remain native Windows paths. Treat /c/Users/... as compatibility input, not the primary model.

Updating

Keep the three update planes separate:

winuxsh --self-update --check
winuxsh --self-update

winuxcmd.exe wpm update winuxcmd

winuxsh plugin update oh-my-winuxsh --github-release latest
winuxsh plugin rollback oh-my-winuxsh

• winuxsh --self-update updates the shell.
• wpm update winuxcmd updates command packages and command links.
• plugin update oh-my-winuxsh updates the official plugin bundle.

Debug Checklist

For shell issues, capture the active binary and execution path first:

winuxsh --version
command -v winuxsh
command -v winuxcmd.exe
echo "$SHELL"
winuxsh -c 'echo command-mode:$SHELL'
winuxsh -C 'echo repl-command:$SHELL'

For repository changes, run focused tests before broad suites:

cargo test --test repl_command --locked
cargo test -p winuxsh-runtime --lib --locked
cargo test --test plugin_inventory --locked

Use Plugin System Direction for architecture and Plugin System Roadmap for execution order.

Installer and Self-Update

Winuxsh ships two Windows package shapes:

• winuxsh-v<version>-win-<arch>-setup.exe for normal users.
• winuxsh-v<version>-win-<arch>.zip for portable, agent, or scripted use.

The installer is built with Inno Setup and installs per user by default under:

%LOCALAPPDATA%\Programs\Winuxsh

It does not require administrator privileges. The default installer tasks:

• add the install directory to the user's PATH;
• add or update a Windows Terminal profile named Winuxsh;
• set that profile's command line to the installed winuxsh.exe;
• set that profile's starting directory to %USERPROFILE%;
• point the Windows Terminal profile icon at the installed PNG asset.

The Windows Terminal profile is installed by running:

winuxsh --install-wt-profile --quiet

Users can run this command again after moving an install. To also set Winuxsh as the Windows Terminal default profile, run:

winuxsh --install-wt-profile --set-default

Self-update uses Windows WinHTTP directly to follow the GitHub Release releases/latest redirect, download the latest installer for the current architecture, and start it silently. It does not depend on the GitHub REST API.

winuxsh --self-update

Inside an interactive Winuxsh REPL, use:

self-update

The REPL command hands the update to a child process and exits the current shell so the installer can replace winuxsh.exe.

Useful dry-run modes:

winuxsh --self-update --check
winuxsh --self-update --dry-run

Interactive shells check for updates at most once per day. The check is best-effort and silent on network failures; when a newer release exists, Winuxsh prints a short hint to run self-update in the REPL or winuxsh --self-update outside it. Set WINUXSH_UPDATE_CHECK=0 or WINUXSH_NO_UPDATE_CHECK=1 to disable the reminder.

The portable zip keeps the same first-start WinuxCmd activation flow: if command links are missing, Winuxsh runs winuxcmd/activate-winuxcmd.sh once from the bundle so ls, cat, grep, and friends resolve normally.

Updating WinuxCmd with WPM

The Unix command set (ls, cat, grep, sed, ...) is delivered by WinuxCmd and managed separately from the Winuxsh binary. Winux Package Manager (wpm) handles it:

wpm update winuxcmd          # update WinuxCmd from the local index
wpm index status             # inspect the local index state
wpm list                     # indexed packages and install state

wpm update winuxcmd refreshes the command set in place; command links are rebuilt automatically. Run wpm --help for the full surface (index, source, search, info, install, links).

So the update story has two parts:

winuxsh --self-update        # the shell itself
wpm update winuxcmd          # the Unix commands it ships with

Bundled Plugin Baseline

Release packages also stage the official oh-my-winuxsh bundle under:

bundles\oh-my-winuxsh

The runtime checks that app-bundled path after user-managed bundle locations:

%LOCALAPPDATA%\Winuxsh\bundles\oh-my-winuxsh\current
%LOCALAPPDATA%\Winuxsh\bundles\oh-my-winuxsh\<version>
bundles\oh-my-winuxsh

Fresh offline installs can still list and use official plugins, while winuxsh plugin update oh-my-winuxsh ... can replace the baseline without rewriting the application install directory.

tags: [winuxsh, zsh, migration, tutorial] created: 2026-07-19 status: active

Zsh Migration Guide for Winuxsh

This guide is for users who already know zsh / Oh My Zsh and want a similar experience in winuxsh on native Windows.

Winuxsh is not a zsh interpreter. The goal is to preserve the daily zsh feel where it matters while keeping Windows-native process behavior and rubash-owned shell semantics.

Mental Model

Think of winuxsh as three layers:

rubash       -> bash-compatible shell language and execution
winuxcmd     -> Unix coreutils exposed through Windows PATH
reedline     -> zsh-like interactive frontend

Zsh compatibility lives above those layers:

• .zshrc is a source of intent, not code that is blindly executed.
• Oh My Zsh plugins are scanned, classified, and translated when safe.
• Common UX plugins are implemented natively in winuxsh.
• Unsupported zsh internals are reported instead of silently ignored.

What Carries Over Cleanly

These zsh habits should feel familiar:

What Does Not Carry Over Directly

These require native replacements or remain unsupported for now:

• arbitrary zsh functions executed during startup
• arbitrary source plugin.zsh at shell startup
• ZLE scripting internals such as BUFFER, PREBUFFER, region_highlight
• zmodload, zpty, deep completion internals like dynamic compadd
• zsh-only shell syntax that rubash/bash does not support
• plugins that depend on a running zsh interpreter rather than aliases, completion metadata, prompt text, or well-known lifecycle hooks

This is deliberate. Winuxsh must stay Windows-native, agent-friendly, and rubash-owned for shell semantics.

Step 1: Inspect Your Zsh Setup

Run a read-only report first:

winuxsh --zsh-compat-report

For tools or agents, use JSON:

winuxsh --zsh-compat-report-json

The report shows:

• discovered source files
• aliases
• env and PATH entries
• plugin names and tiers
• completion assets
• dynamic completion sources
• native hook/widget suggestions
• prompt/theme translations
• unsupported features with diagnostics

Step 2: Review the Import Plan

Generate a TOML patch without writing anything:

winuxsh --zsh-compat-import-plan

The plan targets ~/.winshrc.toml. It may include:

[zsh]
enabled = true
auto_apply = true
plugins = ["git", "zsh-autosuggestions", "zsh-history-substring-search"]

[editor]
edit_mode = "vi"

[aliases]
gst = "git status"

[shell]
prompt_format = "{user}@{host} {cwd} {git_prompt} {symbol}"

Do not apply a plan you do not understand. Unsupported zsh behavior should stay visible in the report.

Step 3: Apply Explicitly

Apply only after review:

winuxsh --zsh-compat-import-apply

Winuxsh creates a backup before writing and only replaces its managed import block. User-authored TOML outside that block is preserved.

Check the result:

winuxsh --zsh-compat-import-status
winuxsh --zsh-compat-doctor

If you need to inspect rollback instructions:

winuxsh --zsh-compat-import-rollback-plan

Step 4: Inspect Plugin Mappings

Winuxsh maps common zsh plugin intent to Winuxsh-native features. Prefer the current plugin inventory for new work:

winuxsh plugin list
winuxsh plugin search git
winuxsh plugin review git

Legacy migration inventory is still available:

winuxsh --zsh-native-packs

Machine-readable version:

winuxsh --zsh-native-packs-json

Important distinction:

• listed means winuxsh knows how to map that migration intent.
• enabled by default is intentionally much smaller.

Default-on safe UI packs:

• zsh-autosuggestions
• zsh-syntax-highlighting

Recommended low-risk daily profile, available as zsh-lite:

• git
• zsh-autosuggestions
• zsh-history-substring-search
• standard ZLE widget mappings

Explicit-trust packs stay opt-in:

• direnv
• dotenv
• zoxide
• thefuck
• command-not-found
• fzf
• zsh-interactive-cd
• last-working-dir

Step 5: Configure Daily Zsh-Like UX

Generate a reviewable low-risk daily profile:

winuxsh --zsh-profile-plan zsh-lite

For a deterministic profile suited to agents and non-interactive work:

winuxsh --zsh-profile-plan agent

--zsh-profile-plan prints TOML only. Review it before merging it into ~/.winshrc.toml; automatic --zsh-profile-apply is still a later phase.

Example starting point:

[zsh]
enabled = true
auto_apply = true
plugins = ["git", "zsh-autosuggestions", "zsh-history-substring-search"]
compat_level = "safe"

[zsh.native_widgets]
enabled = true
presets = ["autosuggestions", "history_substring_search"]
import_bindkeys = true

[zsh.native_plugins]
enabled = false
presets = []

[editor]
edit_mode = "vi"

[shell]
prompt_format = "{user}@{host} {cwd} {git_prompt} {symbol}"
multiline_indicator = "> "
history_search_indicator = "history: "
history_search_fail_indicator = "history: no match "

[history]
path = "~/.winuxsh_history"
max_size = 10000
ignore_space_prefixed = true

[completions]
matching = "prefix"
case_sensitive = false
max_command_results = 500

[menus]
completion_page_size = 10
history_page_size = 10
max_entry_lines = 5

Keep lifecycle packs disabled until you decide what should run in each project.

Git Plugin Experience

The native Git pack provides common Oh My Zsh-style aliases such as:

User aliases win over native aliases. If your .zshrc already defines gst, winuxsh preserves your version.

Prompt support includes native {git_prompt} rendering for common Oh My Zsh git_prompt_info patterns.

Windows Path Rules

Winuxsh is Windows-native, so prefer:

cd C:/Users/you/repo
ls C:/Users/you

Also accepted:

cd C:\Users\you\repo
ls /c/Users/you

But default output should stay Windows-native:

pwd
# C:/Users/you/repo

If a command receives /c/..., winuxsh treats it as compatibility input and normalizes it before invoking native Windows tools where needed.

Agent Usage

Agents should prefer deterministic non-interactive entry points:

winuxsh -c "pwd; ls; cargo test"
winuxsh script.sh

Guidelines:

• Do not rely on interactive plugin prompts in -c or script mode.
• Keep lifecycle plugins opt-in and project-aware.
• Use --zsh-compat-report-json and --zsh-native-packs-json for migration diagnostics.
• Prefer C:/... paths in generated commands.

Troubleshooting

The import plan is empty

Check whether winuxsh is scanning the right zsh directory:

[zsh]
zdotdir = "~"
import_zshrc = true
import_oh_my_zsh = true

Then run:

winuxsh --zsh-compat-doctor

A plugin is reported unsupported

That usually means it needs zsh internals. Look for an official Winuxsh plugin first:

winuxsh plugin search <name>

If no pack exists, the plugin may need a future native implementation rather than direct zsh sourcing.

A dynamic completion does not run

Dynamic completions are disabled by default. They need explicit allowlists, timeouts, and cache settings because they execute external commands.

A path looks like /c/Users

That should only be compatibility input. Default visible cwd output should be C:/Users/.... If prompt, pwd, and native child process cwd disagree, that is a host contract bug.

Roadmap

Near-term zsh onboarding work:

1. Native pack manifest and CLI inventory: implemented.
2. zsh-lite / agent profile planner: implemented.
3. Git daily-use polish: planned.
4. Widget pack polish: planned.
5. Tool pack expansion for gh, cargo, pnpm, python, and related CLIs: planned.
6. README and tutorial expansion: active.

Golden Rule

Do not make winuxsh safer or more compatible by pretending to be zsh. Make it useful by translating zsh intent into tested Windows-native behavior.

Rubash Bash Compatibility Matrix

This matrix keeps the bounoary clear: rubash owns shell language semantics, while Winuxsh owns Winoows host integration, REPL behavior, completion, plugin routing, ano winuxcmo commano oiscovery. Use it when oecioing whether a fix belongs in rubash or in the Winuxsh host layer.

Verification Layers

Focuseo Compat Fixtures

Host Contract Coverage

Known Gaps ano Routing

Maintenance Rules

• Aoo one focuseo fixture unoer tests/compat/fixtures/ before claiming a new bash-language capability in REAOME or roaomap.
• Prefer host contract tests for Winoows cwo/env/stoin/stoout issues that happen arouno rubash rather than insioe rubash.
• Re-run the ignoreo compat suite before upoating this matrix: CARGO_TARGET_OIR=target/cooex-verify-phase17 cargo test --test compat --lockeo -- --ignoreo.
• Use the upstream local gate only when parser/executor behavior changes or when syncing a new rubash revision.

Winuxsh v2 Architecture

基于 rubash + winuxcmd 的 Windows 原生 bash/zsh-like terminal

项目定位

winuxsh 是一个 Windows 原生、无隔离、给人和 agent 都可以直接使用的 bash/zsh-like terminal。它不自己实现 shell 语言，而是作为 rubash lib（bash 兼容引擎）的交互式前端 + winuxcmd（coreutils）的路由层。它的核心价值在于 Windows 原生进程/环境体验：reedline REPL、补全系统、主题系统、Ctrl+C 处理、终端集成，以及稳定的非交互式 agent 执行契约。

winuxsh 不是 MSYS2、Git Bash、Cygwin 或 WSL 风格的隔离环境。~ 指向普通 Windows 用户 home（PowerShell 中的 home / USERPROFILE / dirs::home_dir()），PATH、cwd、env、stdout、stderr、exit code 都是正常 Windows 进程状态。

三层架构

winuxsh.exe
├── winuxsh 自身层 (Rust)
│   ├── rubash::Executor         ← shell 语言引擎 (lexer/parser/execution/builtins)
│   ├── reedline REPL            ← 行编辑、历史、补全
│   ├── completion/              ← TOML + bash 自动导入 + 三级缓存
│   ├── theme/                   ← 主题 API / schema / bundle loader
│   ├── config                   ← legacy/managed .winshrc.toml 解析
│   ├── plugins                  ← Winuxsh 官方插件 registry / bundle 控制面
│   └── ctrl_c                   ← Win32 Ctrl+C 处理
├── rubash lib (Rust)
│   ├── lexer/parser/ast
│   ├── executor (pipeline/redirect/alias/function/array/job)
│   └── builtins (cd/source/export/set/test/printf...)
└── winuxcmd.exe (C++)           ← Unix coreutils (ls/cat/grep/find/cp/mv/rm...)

关键设计决策

1. rubash 作为 lib 依赖

winuxsh 直接链接 rubash 作为 Rust crate 依赖：

[dependencies]
rubash = { git = "https://github.com/unixwin/rubash.git", branch = "master" }

所有 shell 语义（解析、执行、内建命令、变量展开、重定向、管道、作业控制）委托给 rubash。winuxsh 不重复实现 lexer/parser/ast/builtins。

2. winuxcmd 通过 PATH 注入集成

不是通过 FFI/DLL——rubash Executor 内部通过 find_user_command() 在 PATH 查找外部命令。winuxsh 在启动时：

1. 探测 winuxcmd.exe 位置（优先 exe 同目录、其次 PATH）
2. 将其所在目录前置到进程 PATH 环境变量
3. rubash 的 PATH 查找自然先命中 winuxcmd 提供的 ls/cat/grep 等命令

3. 补全系统独立于引擎

补全系统（TOML 定义 + bash 脚本自动导入 + cmd -h 描述抓取 + 三级缓存）在 winuxsh 侧实现，不依赖 rubash。这是 winuxsh 的核心差异化能力。

4. 配置与启动入口

• ~/.winuxshrc 是主要交互式入口，用普通 winuxsh/bash 语法声明插件列表、 主题、prompt 模板、export、alias、函数和本地启动逻辑。
• ~/.winshrc 是兼容 fallback；只有 ~/.winuxshrc 不存在时才作为旧用户 rc 启动文件读取。
• ~/.winshrc.toml 继续作为 legacy/managed 结构化状态读取，用于 plugin CLI enable/disable 记录、权限、bundle 版本、zsh migration blocks、测试隔离、补全 目录、WinuxCmd override 等机器可编辑状态。
• 当 ~/.winuxshrc 存在时，它是 source plugin/framework 的入口；host 不再 同时从 TOML 默认插件状态偷偷 source 一遍官方 source plugins，避免双入口和 prompt/Git 状态重复刷新。
• 普通 winuxsh -c、脚本文件和 stdin 脚本仍保持安静确定，不加载交互式 rc 或 source plugins。

设计原则是减少人类可见入口：用户日常只改 ~/.winuxshrc；TOML 留给兼容、 迁移、CLI 管理和可审计机器状态。

5. 插件系统

v3 插件系统是 Winuxsh 自己的插件系统，不是 zsh 插件兼容层。

• oh-my-winuxsh 作为官方 bundled plugin distribution 随 winuxsh 发行。
• git/docker/kubectl/npm 这类 Oh My 风格 shell helper 可以作为 kind = "source" 的 first-party pack，从 bundle 内 init.winux 加载。
• zoxide/direnv/dotenv/fzf 等需要更强 host 行为的能力继续由 kind = "builtin" 或后续显式 effect/runtime API 承接。
• WASM/WASI 是第三方插件的长期运行时。
• process/IPC 插件是外部工具桥和调试后端。
• 插件不能扩展 rubash parser/executor，也不能 source 任意 zsh、legacy .winsh、或用户目录里发现的 rc 片段。source pack 只能加载 manifest 声明的 bundle-local .winux 文件，并且需要 shell:source 权限。
• Winuxsh 不支持 ZLE runtime；只允许把少量 zsh 风格键位名翻译到 reedline 原生编辑动作。

目录结构

winuxsh/
├── Cargo.toml
├── LICENSE                   # GPL-3.0-or-later
├── README.md / README-zh.md
├── .winuxshrc                 # primary interactive user entry
├── .winshrc                   # legacy fallback rc
├── .winshrc.toml              # legacy/managed structured state
├── crates/
│   └── winuxsh-runtime/
│       ├── Cargo.toml
│       └── src/
│           ├── lib.rs        # 库入口
│           ├── shell.rs      # Shell 状态
│           ├── repl.rs       # reedline REPL
│           ├── ctrl_c.rs     # Win32 Ctrl+C
│           ├── config.rs     # 配置解析
│           ├── winuxcmd.rs   # winuxcmd 探测
│           ├── prompt.rs     # Prompt 渲染
│           ├── theme.rs      # 主题系统
│           └── completion/   # 补全系统
├── src/
│   └── main.rs               # 入口
└── docs/
    ├── src/
    │   └── (this documentation book)
    └── planning/

数据流

用户输入 "ls -la | grep foo"
         │
         ▼
   reedline (行编辑 + 补全)
         │
         ▼
   shell.execute_line(line)      ← winuxsh-runtime
         │
         ├─ rubash::lexer::tokenize(line)
         ├─ rubash::parser::parse(tokens) → Ast
         └─ executor.execute_ast(&ast)    ← rubash 处理全部语义
                │
                ├─ 内建命令 (cd/source/echo...)
                ├─ 外部命令 → find_user_command("ls")
                │                   │ (PATH 已注入 winuxcmd 目录)
                │                   ▼
                │              winuxcmd.exe ls -la
                │
                ├─ 管道: | grep foo → find_user_command("grep")
                └─ 输出到 stdout

与旧架构的差异

版本规划

• v2.2: rubash rewrite 稳定化、补全增强、Vi/Ctrl+R、配置一致性、用户主题
• v2.3: Windows 原生 terminal contract、agent 友好的非交互式行为、history/prompt/completion UX
• v2.4: zsh-like 交互体验 polish（右 prompt、提示、补全菜单、默认配置）
• v3: 内置 Winuxsh 插件系统；oh-my-winuxsh 作为官方 bundled plugin distribution；先用 builtin registry 统一现有 first-party packs，再引入 WASM/WASI 作为第三方插件运行时。zsh 兼容保持一次性迁移/维护层。
• 非目标: Linux/macOS 原生 shell 产品；rubash 可跨平台复用，但 winuxsh 产品目标是 Windows

Last updated: 2026-07-30

tags: [winuxsh, roadmap, v2] created: 2026-07-13 status: active

Winuxsh Roadmap

Windows 原生、无隔离、给人和 agent 使用的 bash/zsh-like 终端 核心公式: winuxsh = rubash (shell 引擎) + winuxcmd.exe (coreutils) + reedline (REPL)

已完成 (v2 重写)

• rewrite/v2-rubash 分支落地,单 commit c7e2c3c (+1514/-17817)
• rubash 作为 lib 依赖,不再自实现 lexer/parser/ast/builtins
• winuxcmd 通过 PATH 注入集成,不依赖 FFI/DLL
• 补全系统 (TOML + bash 自动导入 + 三级缓存 + ListMenu)
• 主题系统 (4 内置主题: default/dark/light/colorful)
• Ctrl+C Win32 处理
• REPL (reedline + 历史文件 .winuxsh_history)
• 上游 PR unixwin/rubash#5 合入 (Windows PATH 大小写修复)
• cargo build 零警告,14/14 测试通过
• architecture.md、v2-plan.md 落盘 vault

当前方向更新 (2026-07-30)

• Zsh / Oh My Zsh 兼容层进入迁移与维护模式：保留 scanner、import-plan、 诊断和一次性 onboarding，但不再把 zsh 插件、ZLE 或 Oh My Zsh 兼容作为 插件系统身份。
• v3 主线转向 Winuxsh 自己的内置插件系统：oh-my-winuxsh 是官方 bundled plugin distribution，随 winuxsh 发行并支持独立更新/回滚。
• 插件实现顺序改为：先用 kind = "builtin" registry 接管现有 first-party packs， 再做 process bridge，最后做 WASM/WASI 第三方运行时。
• rubash 始终跟随 unixwin/rubash master 最新版本；shell 语义缺口优先在 rubash 上游修复，再由 winuxsh 更新依赖验证。

短期 - v2.1

CI 基础设施

• .github/workflows/ci.yml - push/PR 自动 cargo build + cargo test (PR #9 合入)
• Windows 平台 (当前仅支持 Windows)
• cargo fmt --check lint 步骤

兼容性测试套件

• tests/compat/ 目录, .sh + .expected 配对
• 覆盖: 变量展开、命令替换、管道、if/for/case/function、别名、exit code、echo flags (heredoc 待 T-4)
• 通过 cargo test --test compat -- --ignored 运行 (10 个 fixture)

master 合并

• PR #9: rewrite/v2-rubash -> master, 已 squash 合并到 master (commit a50638f) 修复了 cargo fmt --check 与 Cargo.lock tracked 问题，CI 全绿

脚本执行改进

• T-4: execute_script 整体 tokenize+parse+execute，支持 heredoc / continuation / 多行 if/for (commit 792416f)

中期 - v2.2

工作方式

• 先做 Nushell / 现代 Windows shell reference audit，仅参考设计，不引入 Nushell 依赖，不 vendor 外部源码
• 每个功能阶段先更新 Markdown 计划，再小步实现、测试、提交（v2.2 实施中）
• Obsidian vault 中维护 winuxsh/ 文件夹作为项目长期记忆
• Nushell reference audit 落盘: docs/planning/nushell-reference-audit.md
• zsh / Oh My Zsh / zsh 插件 reference audit 落盘: docs/planning/zsh-reference-audit.md
• zsh-first 功能定位与现代 shell reference map 落盘: docs/planning/winuxsh-positioning-and-feature-map.md
• Windows 原生 agent/user terminal 下一步计划落盘: docs/planning/winuxsh-next-development-plan.md
• zsh 配置与插件兼容计划落盘: docs/planning/zsh-compatibility-plan.md
• zsh 兼容接口可行性审计落盘: docs/planning/zsh-compatibility-interface-audit.md
• Phase 0 hygiene: 清理误建的空 --help 目录，保留 .tmp/ 未跟踪

补全系统增强

• Phase 1 baseline: 修复 completion integration test stale API (load_completion_dirs)
• Phase 2 foundation: 内置 ls / grep / find 默认补全定义
• Phase 3 expansion: 内置 cat / cp / mv / rm / mkdir / touch / chmod 默认补全定义
• 扩充默认 TOML 补全定义的命令覆盖范围
• bash 自动导入覆盖更复杂的 complete 调用模式
• 补全三级缓存的 TTL/失效策略

配置一致性

• Phase 5 config: [winuxcmd].path 参与 PATH injection

用户体验 (v2.2)

• 引导式配置向导 (首次运行交互式问答, 自动生成 ~/.winshrc.toml)

• {time}/{time_24} prompt 模板变量 (右侧时间提示)

• 5 种 prompt 预设样式 (minimal/classic/powerline/multiline + right prompt options)

• Unicode 提示符号预设: 设置向导可选 ❯ λ ▶ $ % 等符号

• 配置化 prompt_symbol: config TOML + ShellConfig + WinuxshPrompt 全链路

• 内置 40+ oh-my-zsh 风格 git 别名 (gst, gco, gp, gl, gd 等)

• 补全系统增强: PATH 命令缓存 + 空 Tab 显示常用命令列表

• 已修复: cd .. 不改变进程 cwd 的 bug

• 已修复: /c/Users 路径格式不被 winuxcmd 识别的 bug

• 已修复: C:\ 反斜杠路径被 tokenizer 吃掉的 bug

• Vi 模式 (reedline 原生支持,主要工作量在键位配置)

• Ctrl+R 历史搜索 (reedline 原生)

• 更多 prompt 自定义模板

• Phase 6 themes: 用户自定义主题加载 (从 ~/.winuxsh/themes/)

• zsh compat report CLI: 先输出扫描报告，不自动修改启动行为

• zsh profile scanner/apply 第一层: [zsh].auto_apply 安全导入 .zshrc env/PATH/alias

• Oh My Zsh layout importer Phase 2a: 静态 _cmd / #compdef / _arguments completion 资产翻译

• zsh plugin tier importer Phase 2b: 插件分层报告 completion-only / alias-only / native-needed / unsupported

• 原生 autosuggestions Phase 4a: 参考 zsh-autosuggestions，用 reedline history hinter 实现

• 原生 syntax highlighting Phase 5a: 参考 zsh-syntax-highlighting main highlighter，用 reedline 实现

• zsh prompt/theme compatibility Phase 6a: 扫描 PROMPT / RPROMPT 与简单 Oh My Zsh theme，翻译为 native prompt template

• zsh Git prompt compatibility Phase 6b: 将 $(git_prompt_info) 桥接到 native {git_prompt} / .git/HEAD 渲染

长期 - v3

插件框架

• v3 design doc opened: winuxsh-v3-plan.md
• 插件 manifest schema：kind = "builtin" | "wasm" | "process" 已用于 registry/bundle manifest
• Winuxsh plugin registry：现有 first-party builtin packs 已注册为官方 packs
• [plugins] TOML 控制面：已解析 enablement、permissions、bundles、load；managed block/apply 待做
• 插件 CLI：plugin list/info/search/review/doctor/install/uninstall 与 plan enable/disable、enable/disable、update/rollback 已接入
• 完整执行路线：plugin-system-roadmap.md
• oh-my-winuxsh bundled distribution：随 release 内置，支持独立版本更新
• Phase 8 WASM command host：command modules 已支持 sha256 校验、memory cap、fuel timeout、exit code
• Phase 14 WASM host IO ABI：winuxsh:plugin/host 支持受限 stdout/stderr 写入，缺失 memory / 越界 / 超限返回 -1
• Phase 15 WASM command args ABI：arg_count/arg_len/arg_read 支持显式读取简单命令参数，非法 index / 缺失 memory / 越界返回 -1
• Phase 16 WASM cwd read ABI：cwd_len/cwd_read 在 manifest 声明 cwd:read 后暴露 shell-visible PWD，无权限 / 缺失 memory / 越界返回 -1
• WASI/component host 与第三方长期运行时：后续扩展 completion/prompt/transform 能力
• process/IPC 插件 bridge（外部工具适配与调试后端）：显式 opt-in、权限、timeout、command/hook fixture 已验证

Oh-My-Winuxsh

• 重建 unixwin/oh-my-winuxsh：本地保留 legacy state，当前分支改为官方 Winuxsh plugin bundle
• bundle.toml 与 first-party packs/*/plugin.toml
• 同步路线：oh-my-winuxsh/docs/roadmap.md
• bundle baseline 随 winuxsh release 打包
• ~/.winuxsh/plugin-lock.toml 记录 bundle 版本、checksum、active/rollback path（本地 release artifact 已接入）
• winuxsh plugin update oh-my-winuxsh --from <path> 独立安装/切换官方 bundle
• winuxsh plugin update oh-my-winuxsh --github-release latest|vX.Y.Z 下载官方 release zip 与 .sha256 后进入同一校验/切换路径
• Phase 9 discovery/review/doctor：plugin search/review/doctor 覆盖 active official inventory、权限审计、缺失 binary 和 drift 诊断
• Phase 9 install/authoring：plugin install/uninstall 写入 managed [plugins]；oh-my bundle 提供 index、templates、authoring docs 和 CI gate
• Phase 6 first-party assets：alias、completion、prompt preset、keybinding metadata 已由官方 bundle 接管，runtime 保留 compiled fallback
• Phase 11 theme pack foundation：官方 bundle 可声明/校验/发布 theme assets，runtime 可从 active bundle 加载非内置主题
• Phase 13 theme market discovery：winuxsh plugin themes [--json] 只读列出 built-in / user / active bundle 主题来源，为后续第三方主题分发保留产品层
• Phase 14-17 WASM host ABI：oh-my 文档声明 stdout/stderr、simple argv、permission-gated cwd/env read 是当前 WASM public contract，WASI/component/shell mutation 仍未开放
• Phase 7a import-plan CLI: --zsh-compat-import-plan 输出可审阅 .winshrc.toml patch，不自动写用户配置
• Phase 7b import-apply CLI: --zsh-compat-import-apply 显式写入 .winshrc.toml，写前备份，仅替换 winuxsh 管理块
• Phase 7c import-status CLI: --zsh-compat-import-status 只读检查 managed block / TOML / 备份 / 下一次 apply 可行性
• Phase 7d rollback-plan CLI: --zsh-compat-import-rollback-plan 只读输出最近备份与恢复命令
• Phase 7e doctor CLI: --zsh-compat-doctor 聚合 scan/status/rollback，给出安全 apply 判断和下一步命令
• Phase 8a legacy native pack: plugins=(git) 缺少 OMZ 插件目录时提供保守 git alias pack，不覆盖用户 alias；后续迁移到 oh-my-winuxsh/git
• Phase 8b legacy native pack: plugins=(docker) 缺少 OMZ 插件目录时提供保守 docker alias pack，不覆盖用户 alias；后续迁移到 oh-my-winuxsh/docker
• Phase 8c dynamic completion scan: 识别 tool completion zsh 这类动态 completion generator，报告为 native provider 待接入
• Phase 8d dynamic completion translation: 用注入 runner 将 tool completion zsh 输出翻译为 winuxsh CommandDef，尚不在启动时执行外部命令
• Phase 8e dynamic completion runner: 显式 allowlist + timeout 执行动态 generator，默认不运行外部命令
• Phase 9 dynamic completion provider: [zsh.dynamic_completions] 配置、磁盘缓存、启动接入，默认关闭
• Phase 10a kubectl preset: plugins=(kubectl) 缺少 OMZ 目录时提供 native alias pack + disabled dynamic completion preset
• Phase 10b npm preset: plugins=(npm) 缺少 OMZ 目录时提供安全 npm alias pack，并标记 F2/ZLE toggle 为 native UX 待实现
• Phase 10c dynamic plugin shape scan: 区分 script_generator 与 runtime_provider，并标记 ZLE/hook/autoload 这类动态插件机制
• Phase 11a runtime completion provider: [zsh.runtime_completions] 显式 allowlist + timeout，在 Tab 时接入 npm-style completion -- "${words[@]}" 动态候选
• Phase 12a native lifecycle hooks: [hooks] 支持 precmd / preexec / chpwd REPL hook surface，不 source zsh 函数体
• Phase 12b native hook suggestions: 扫描 add-zsh-hook / *_functions / hook 函数定义，输出可审阅 [hooks] TODO，不自动执行
• Phase 13a keybinding migration suggestions: 扫描 zle -N / custom bindkey，输出可审阅 native reedline keybinding TODO；不支持 ZLE runtime
• Phase 14a keybinding presets: 旧 [zsh.native_widgets] 兼容读取后，将 recognized autosuggest/history keybinding 名称映射到 reedline event
• Phase 14b native UX plugin presets: 缺少插件目录时也将 zsh-autosuggestions / zsh-history-substring-search / syntax-highlighting 类插件归为 native UX
• Phase 15a autoload/function suggestions: 扫描 autoload 与函数定义，按 completion/hook/widget/prompt/helper 形态输出报告和 import-plan TODO
• Phase 16a native dynamic plugin preset: direnv 通过旧显式 opt-in，在 native precmd/chpwd hook 点运行 direnv export bash
• Phase 16b native dynamic plugin preset: alias-finder 通过旧显式 opt-in，在 native preexec hook 点提示已知 alias
• Phase 16c native dynamic plugin preset: zoxide 通过旧显式 opt-in，提供 native z command shim 并用 lifecycle hook 记录目录
• Phase 16d native dynamic plugin preset: thefuck 通过旧显式 opt-in，提供 native fuck correction shim，基于上一条交互命令调用 thefuck
• Phase 16e native dynamic plugin preset: command-not-found 通过旧显式 opt-in，在命令缺失时输出 Windows-native 安装搜索提示
• Phase 16f native selector plugin preset: fzf / zsh-interactive-cd 通过旧显式 opt-in，提供 native cdf / fzf-cd 目录选择 shim
• Phase 16g native state plugin preset: last-working-dir 通过旧显式 opt-in，提供 native lwd 与交互 REPL 启动目录恢复
• Phase 16h native env plugin preset: dotenv 通过旧显式 opt-in，安全解析当前目录 .env 并写入 rubash env
• Windows-native host contract stabilization: cd 后同步 rubash PWD 与 process cwd，pwd 默认显示 C:/...，winuxcmd 路径参数兼容旧 /c/... 输入，空输入/前缀命令补全恢复
• Phase 18 completion probe: 新增非交互 --completion-probe 入口，覆盖空 Tab、前缀命令、PATH/PATHEXT、管道后命令位与参数位不误补全
• Phase 19 blank argument path completion: 修复 cd <Tab> / ls <Tab> 这类空参数位不返回当前目录候选的问题
• Phase 20 path completion polish: 保留目录前缀、转义空格路径、隐藏文件按 . 前缀显示、目录优先排序
• Phase 21 shell-word-aware completion: 补全切词理解反斜杠转义和简单引号，修复 two\ w / "two w 这类路径补全
• Windows cwd authority regression: 启动时以真实 process cwd 初始化 rubash PWD，且 cd target; native-child 同一交互行中同步 process cwd，避免 prompt/ls 与 PWD 分裂
• Phase 22 prompt indicator polish: [shell] 支持 emacs/vi/default/multiline/history-search prompt indicators，补齐 zsh-like 模式提示入口
• Phase 23 history config polish: [history] 支持 history path、max size、ignore-space-prefixed，保持默认 ~/.winuxsh_history
• Phase 24 completion UX config: [completions] 支持 case sensitivity、prefix/substring matching、max command results
• Phase 25 menu UX config: [menus] 支持 completion/history page size 与 max entry lines
• Phase 26 zsh-style keybinding name subset: 常见 bindkey KEY action-name 映射到 reedline 原生事件；不执行 ZLE 函数体
• Phase 27 native Windows path literals: 裸 C:\... 输入在 rubash tokenization 前规范化为 C:/...，避免反斜杠被 bash 词法当作转义符吞掉
• Phase 28 interactive multiline collector: REPL 识别未完成的 if/for/while/case/function 等复合命令块，显示 PS2/continuation prompt，完整后一次性交给 rubash script execution
• Phase 29 bash smoke fixture: 将用户手工 20 段 bash/zsh-like smoke 脚本整理为可持续 compat fixture，优先覆盖条件判断、循环、函数、重定向、路径与 exit status
• Phase 30 rubash AND/OR status semantics: 修复 false && a || b / [ ... ] && a || b 这类 AND/OR list 跳过语义，保持 shell 语义在 rubash，不在 winuxsh 重建执行器
• Phase 31 legacy native pack manifest: 列出现有 git/docker/kubectl/npm/keybinding/lifecycle packs，并提供只读旧 CLI inventory (--zsh-native-packs / --zsh-native-packs-json)；后续迁移到 winuxsh plugin list
• Phase 31b legacy cleanup: 旧 CLI inventory 保留为迁移兼容入口，用户文档和帮助文案迁移到 winuxsh plugin ...
• Phase 32 zsh-lite profile plan: 基于现有 [zsh] / [zsh.native_widgets] / [zsh.native_plugins] 生成可审阅默认 zsh-like 配置块
• Phase 33 Git daily-use polish: git <Tab> / 子命令 / flag 补全已接入并测试，README 补齐 alias、completion、prompt 文档，让 git 插件成为第一等 daily shell 能力
• Phase 33a oh-my-zsh-style git prompt status: 新增 crates/winuxsh-runtime/src/git_status.rs 通过 git status --porcelain -b / rev-list / stash list 收集 branch/dirty/staged/unstaged/untracked/deleted/ahead/behind/stashes/conflicts；prompt 模板新增 {git_dirty} / {git_staged} / {git_unstaged} / {git_untracked} / {git_deleted} / {git_ahead} / {git_behind} / {git_stashes} / {git_conflicts} / {git_status} 紧凑串；theme 新增 git_clean / git_dirty / git_status_detail 着色；{git_prompt} 默认形如 git:(main) ●2 ↑1 ↓1 ?3，clean=green / dirty=yellow；completions/defaults/git.toml 内置 add/commit/push/pull/checkout/switch/branch/merge/rebase/reset/restore/stash/status/log/diff/init/clone 子命令补全
• Phase 34 p10k-style segment-based prompt engine: new prompt_segments.rs module with 5 presets (lean/classic/rainbow/pure/robbyrussell), powerline separators, multiline prefixes
• README / tutorial documentation baseline: README.md / README-zh.md 重写为用户入口，新增 docs/src/zsh-migration-guide.md 迁移教程
• Plugin system direction refresh: docs/planning/plugin-system-direction.md 改为 Winuxsh-native plugin system + bundled oh-my-winuxsh
• Oh My Winuxsh bundle plan: docs/planning/oh-my-winuxsh-bundle-plan.md 定义重建、bundle、更新、lockfile 和迁移策略
• Plugin registry implementation: builtin packs first, then process bridge, then WASM/WASI
• zsh/Oh My Zsh 兼容导入层维护：只修 bug、保安全导入，不继续扩大为 zsh runtime 或 zsh plugin support

Rubash 能力验证

• Rubash/bash 能力矩阵：新增 docs/src/rubash-bash-compat-matrix.md，按 compat fixtures、host contract、本地 GNU Bash upstream gate 分层记录已验证能力和缺口
• Winuxsh host GNU Bash upstream gate (2026-07-28): 新增 scripts/run-bash-upstream-with-winuxsh.sh，shell under test 指向 winuxsh/target/debug/winuxsh.exe，结果 86 total / 86 pass / 0 fail， summary 位于 target/bash-upstream-tests/summary.md； 本地执行说明见 docs/planning/bash-upstream-local.md，不纳入默认 CI，也不 vendor Bash upstream tests
• Phase 17 host contract matrix: 为 winuxsh host 层补充 PATH/env/cwd/home/stdout/stderr/exit-code 二进制级集成测试
• Phase 18 completion probe tests: 通过 winuxsh --completion-probe 验证真实 Shell 初始化后的 REPL 补全候选
• Phase 19 path completion tests: 覆盖空参数位路径补全，并保持管道后空命令位仍补命令
• Phase 20 path polish tests: 覆盖 src/ma 不丢前缀、空格文件名转义、隐藏文件过滤和目录优先排序
• Phase 21 shell word tests: 覆盖转义空格匹配、引号内路径匹配、补全替换 span 不截断 token
• REPL cwd sequence tests: 覆盖 execute_line("cd target; cwdprobe") 中 Windows .cmd 子进程 cwd 与 PWD 一致
• Phase 22 prompt indicator tests: 覆盖 emacs/vi insert/normal、多行提示、Ctrl+R history search passing/failing 模板
• Phase 23 history config tests: 覆盖默认 history、~ 路径展开、max size、ignore-space-prefixed reedline 接入
• Phase 24 completion UX tests: 覆盖默认 prefix、substring、case-sensitive path、command result cap
• Phase 25 menu UX tests: 覆盖默认菜单配置、TOML 解析、zero fallback、reedline menu builder 接入
• Phase 26 keybinding mapping tests: 覆盖常见 zsh-style keybinding 名称映射、import-plan 启用入口、unsupported diagnostics 降噪
• Phase 27 native Windows path tests: 覆盖 ls C:\... 与 cd C:\...; pwd 的二进制级 host contract
• Phase 28 multiline REPL tests: 覆盖 pending buffer 对 if/fi、for/done、函数体、引号、管道续行、反斜杠续行和注释行的完整性判断
• Phase 29 bash smoke tests: 增加聚合 smoke fixture，并确保失败用例先拆成小回归修复后再纳入 smoke
• Phase 30 AND/OR tests: 覆盖 true &&, false &&, true ||, false ||, 以及 [ 1 -eq 2 ] && yes || no
• Phase 31 native pack inventory tests: 覆盖 pack registry text/json 输出，不改变启动行为
• Phase 32 profile plan tests: 覆盖 agent / zsh-lite 生成 TOML 与 managed-block apply/status/rollback 兼容性
• Phase 33 git pack tests: 覆盖 git <Tab>、常见子命令/flag 补全与用户 alias override
• 作业控制/内建命令语义优先走 rubash，不在 winuxsh 重复实现

关键架构决策 (锁定)

• License: GPL-3.0-or-later (与 rubash 一致,同 unixwin org)
• rubash 集成方式: git 依赖,非本地路径
• winuxcmd 集成方式: PATH 注入,非 FFI/DLL
• 配置文件: .winshrc.toml (保留向后兼容)
• 历史文件: .winuxsh_history
• rust-version: 1.70 (minimum)
• rubash 版本策略: 跟随 unixwin/rubash master 最新版本；更新 root Cargo.lock 后验证 winuxsh
• 插件框架: v3 以内置 Winuxsh plugin registry + bundled oh-my-winuxsh 为主线； 先 builtin，再 process bridge，最后 WASM/WASI；zsh 只保留迁移/维护层

参见: architecture.md | plugin-system-direction.md | oh-my-winuxsh-bundle-plan.md | v2-plan.md | rubash-pr-windows-path.md | winuxsh-v2.2-reference-plan.md | winuxsh-v3-plan.md | winuxsh-positioning-and-feature-map.md | winuxsh-next-development-plan.md | zsh-reference-audit.md | zsh-compatibility-plan.md | zsh-compatibility-interface-audit.md | winuxsh-native-zsh-plugin-pack-plan.md | zsh-migration-guide.md