Walkthrough

Documentation update to .claude/docs/conductor-compatibility.md replacing wrapper-first guidance with a preferred "Shell-Level mise Shims" approach for interactive and non-interactive shells; adds per-shell activation snippets, BASH_ENV/ENV export guidance, caveats about PATH/shadowing and shell compatibility, and retains bin/conductor-exec as a fallback.

Changes

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐰 I tuck soft shims in zsh and bash,

So non-interactive shells won't crash.
I export ENV and tidy the PATH,
A fallback wrapper saves the math.
Hop—your agents find the right path.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Greptile Summary

This PR is a documentation-only update to .claude/docs/conductor-compatibility.md, restructuring the mise version-manager compatibility guide to promote shell-level shim activation (.zshenv / BASH_ENV / ENV) as the preferred approach and demoting bin/conductor-exec to a fallback. No runtime code is changed.

Key changes:

• Replaced the old single "Solution" (conductor-exec-first) with a two-tier structure: Preferred (shell shims) and Fallback (conductor-exec)
• Added steps for .zshenv, .bashrc, .profile, and BASH_ENV/ENV exports
• Added a reference to justin808-dotfiles for a concrete implementation example
• Added a caveat about system binaries shadowing mise shims on PATH
• Removed the original "Symptoms" bullet list, which provided useful self-diagnosis hints for developers experiencing this problem

Two issues identified:

1. Clarity: Line 24 describes mise exec as "bypasses PATH entirely," which is misleading — it actually prepends correct directories to PATH.
2. Completeness: The removal of the "Symptoms" section eliminates diagnostic value — developers can no longer self-diagnose whether they have this problem before reading the solution.

Confidence Score: 4/5

• Safe to merge — documentation-only change with no impact on application behavior.
• This is a documentation-only restructuring with no runtime code changes. The score is 4 rather than 5 because two clarifications would improve the guide: (1) the description of mise exec behavior on line 24 could be clearer about how PATH is actually handled, and (2) the removal of the "Symptoms" section reduces the document's diagnostic value for developers trying to recognize if they have this problem. Both are straightforward to address.
• .claude/docs/conductor-compatibility.md — clarify mise exec PATH behavior and restore diagnostic symptoms section.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Shell spawned by Conductor / coding agent] --> B{Shell-level mise\nshims configured?}
    B -- Yes --> C[.zshenv sources\nmise activate zsh --shims]
    B -- No --> F[Use bin/conductor-exec wrapper]
    C --> D[BASH_ENV / ENV exported\nfor child bash/sh processes]
    D --> E{System binary\nshadowing shims?}
    E -- No --> G[✅ Correct tool version used]
    E -- Yes --> F
    F --> H[mise exec --\nsets up correct tool PATH]
    H --> G

_{Last reviewed commit: 8c3f5b6}

Review

Good improvement overall. Promoting shell-level shim activation to the preferred approach is the right direction — it makes the setup self-healing for Conductor, coding agents, and any other non-interactive shell consumers. The three-commit progression (restructure → add examples → fix review issues) shows good iterative refinement.

Key concerns

1. BASH_ENV=~/.bashrc is a footgun (see inline comment on lines 42-43)

This is the most significant issue. BASH_ENV causes bash to source the file before every non-interactive bash invocation, including #!/bin/bash scripts. Most .bashrc files contain interactive-only code (PS1, bind, completions) that breaks in script context. A dedicated ~/.bash_env file containing only the mise activation would be much safer.

2. mise activate bash --shims in .profile breaks on dash (see inline comment on lines 48-51)

.profile is a POSIX sh file. mise activate bash --shims emits bash-specific syntax that dash (default /bin/sh on Ubuntu/Debian) cannot parse. A [ -n "$BASH_VERSION" ] guard is needed.

3. Bullet/code inconsistency (see inline comment on line 21)

Bullet 4 mentions only BASH_ENV, but the code block exports both BASH_ENV and ENV. Minor but worth aligning.

Minor notes

• The .zshenv example lists macOS paths (/opt/homebrew, /usr/local) first with $HOME/.local/bin/mise as the last fallback. A comment like # Linux default on that branch would help Linux users recognize their path.
• Given the code comment noting that ENV is ignored by dash for non-interactive shells, the docs should explicitly call out that #!/bin/sh scripts on Ubuntu/Debian still need conductor-exec regardless of this setup.

Overall the docs are a clear improvement; addressing the BASH_ENV risk and the .profile/dash incompatibility before merging would make the guidance safe for the full range of developer environments this project targets.

Overall this is a useful improvement. The .zshenv example with hardcoded path checks is the right approach for bootstrapping. A few things worth addressing:

.profile with bash-specific activation syntax

Step 3 recommends mise activate bash --shims from .profile, but .profile is also sourced by POSIX sh (/bin/sh), which on many Linux distros is dash. The bash-specific output from mise activate bash --shims will fail or produce errors when evaluated by dash. Consider mise activate sh --shims for .profile instead.

.bashrc/.profile examples have a bootstrapping problem

The snippet uses command -v mise to detect mise, but in a fresh non-interactive shell ~/.local/bin may not yet be on PATH. This silently fails and shims are never activated. The .zshenv example correctly uses hardcoded path checks (/opt/homebrew/bin/mise, etc.) and the same pattern should be used in .bashrc/.profile.

BASH_ENV performance note

export BASH_ENV="$HOME/.bashrc" causes every non-interactive bash -c subprocess to source the entire .bashrc. If .bashrc is slow (nvm, rbenv, brew shellenv, etc.), this noticeably slows down Conductor and agent tool calls. Worth noting that users should keep .bashrc lightweight, or point BASH_ENV at a minimal dedicated file (e.g., ~/.mise_shims.bash) rather than the full .bashrc.

Minor: "bypasses PATH entirely" is inaccurate

The fallback section says mise exec -- "bypasses PATH entirely" — it actually prepends managed binaries to PATH. The original wording "sets up the correct tool versions regardless of the current PATH order" was more accurate.

Overall direction is sound and a genuine improvement. Three inline comments call out the specific issues — the most important being the BASH_ENV + interactive guard pitfall, which can silently break the preferred solution for the majority of users whose .bashrc has an early-return guard for non-interactive shells.

Overall this is a useful doc improvement. Promoting shell-level shim activation over the wrapper script is the right direction. One functional concern and two minor points (detailed in inline comments):

Functional: BASH_ENV -> .bashrc silent failure. Most .bashrc files have a non-interactive guard (e.g. '[ -z $PS1 ] && return') near the top. When bash is launched non-interactively with BASH_ENV set, it sources .bashrc but immediately returns on that guard before reaching the mise activation line. No error is produced, so shims silently fail to load. Fix: either warn users to place the mise activate line before any such guard, or recommend pointing BASH_ENV at a dedicated file (e.g. ~/.mise_shims.sh) with just the activation line and no guards -- cleaner and avoids the pitfall.

Minor 1: The .zshenv code block uses 'bash' as the syntax hint; 'zsh' is more accurate.

Minor 2: The PR description mentions adding a reference to justin808-dotfiles, but it is not in the diff. Intentional omission, or should it be in the Reference section?

Review: Documentation-only, well-structured update

This is a solid improvement — the shell-level shims approach genuinely reduces friction for developers who haven't set up conductor-exec. The doc is technically accurate about the tricky edge cases (dash vs bash, ENV vs BASH_ENV, interactive vs non-interactive). A few items worth addressing:

Path ordering is macOS-centric

The hardcoded mise binary discovery checks /opt/homebrew/bin/mise first, which means Linux users hit three failed -x checks before reaching $HOME/.local/bin/mise (the canonical Linux install location). This runs on every non-interactive shell startup — a minor but unnecessary overhead.

BASH_ENV performance impact deserves explicit mention

The current caveat only says "heavy .bashrc setup slows every non-interactive bash invocation." But ~/.bash_env itself runs mise activate bash --shims on every bash -c invocation — including those from build tools, test runners, Makefile recipes, and CI steps. In repos that spawn many bash subprocesses, this adds up. Worth calling out explicitly alongside the existing trade-offs section.

ENV scope could be more precise

The comment says ENV "only affects interactive sh/dash shells" — this is correct per POSIX spec and for dash specifically, but the phrasing could confuse users who know that some shells (like ksh) honor ENV for non-interactive use too. Scoping the note to "dash/POSIX sh" would be clearer.

Minor: silent failure if mise is not at any known path

If mise isn't at any of the four hardcoded paths, the shim activation silently does nothing, which is hard to diagnose. A command -v mise fallback or a final else echo "warning: mise not found" branch would help with troubleshooting.

Overall the change is a net positive — these are suggestions, not blockers.

Review: Documentation-only, well-researched update

Overall this is a solid improvement — the new shell-level shims approach is accurate, the per-shell examples are correct, and the trade-off/caveat sections are honest and useful. A couple of small issues worth addressing:

BASH_ENV/ENV gap for bash-primary users

The exports for BASH_ENV and ENV are only shown inside the .zshenv example. A developer whose login shell is bash won't have those variables set, so non-interactive bash subshells won't pick up mise either. A sentence (or short .bash_profile snippet) covering that case would close the gap. Inline comment on line 47.

ENV="$HOME/.profile" can double-source on login

.profile is sourced by login shells; setting ENV to the same file means it re-runs in every subsequent interactive sh/dash sub-shell during that session. A small dedicated ~/.shenv (parallel to ~/.bash_env) would be cleaner and idempotency-safe. Inline comment on line 47 covers this too.

Minor: redundant bundle exec in fallback example

bin/conductor-exec bundle exec ruby --version — conductor-exec already routes through mise exec --, so bundle exec is redundant for a version sanity-check. The original bin/conductor-exec ruby --version was clearer. Inline comment on line 100.

Observation: conductor-exec shebang is #!/usr/bin/env zsh

The docs recommend conductor-exec as a fallback for sh/dash code paths. This works fine because conductor-exec is invoked as its own process (the kernel reads its shebang), but it does mean zsh must be installed. Worth a one-liner note for environments where zsh may not be present.

No blockers — happy to approve once the bash-primary-user gap and ENV target are clarified.

Review: Documentation update for mise shim activation

This is a solid improvement with the right structure (preferred solution first, fallback second). A few observations:

Missing dotfiles reference: The PR description mentions adding a reference to justin808-dotfiles, but no such reference appears in the actual diff. The PR description should be updated if this was left out intentionally.

Fish shell users not covered: The doc covers zsh, bash, and sh/dash but not fish. Fish uses ~/.config/fish/config.fish and 'mise activate fish'. Worth at least a brief note pointing fish users elsewhere.

export ENV uses .profile unconventionally: ENV conventionally points to a lightweight dedicated file (e.g., ~/.shrc) rather than .profile. Using .profile as ENV causes it to be sourced on every interactive sh/dash session, not just login shells, potentially triggering login-specific side effects repeatedly. Since the doc acknowledges ENV does not help with non-interactive sh invocations (the actual Conductor use case), the value of this export is very narrow. Consider removing it or using a dedicated ~/.shrc instead.

Ambiguous note on line 84: The line 'Do not use full mise activate bash in .profile' is confusing because the example already uses 'mise activate bash --shims'. The distinction between full activation and shim-only activation is not spelled out. Clarifying why (full activation emits bash-specific shell hook code that breaks POSIX sh) would help readers.