feat(activate): add shims directory as fallback when auto-install is enabled

[ctaintor]

When not_found_auto_install is true (default), the shims directory is now added to PATH after tool installation paths. This allows shims to handle tools that aren't installed yet (triggering auto-install) and tools that exist on the system but aren't managed by mise.

This solves address two unexpected behaviors of auto_install:

1. Subshells would launch only modifying the PATH to point to installed and with the correct version tools. You could find yourself in a situation where e.g. the correct node version is installed but the correct ruby version is not installed – and if yarn called bundler/ruby then it would not trigger the install.
2. relying on the not-found hook meant that the wrong version would be run if the version wasn't installed in mise but did exist in the system

This change makes the shim be a fallback – meaning that as long as you've installed any version of that tool (and thus mise has created a shim), mise will install the intended version when requested.

[gemini-code-assist]

Summary of Changes

Hello @ctaintor, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the mise activation logic by intelligently integrating the shims directory into the PATH environment variable. This modification ensures a more robust and predictable auto-install experience, allowing mise to seamlessly manage tool versions and trigger installations for missing tools, while also respecting system-wide installations as a fallback. The core purpose is to make the mise environment more resilient and user-friendly, especially in scenarios involving subshells and mixed tool management.

Highlights

• Shims Directory as PATH Fallback: The shims directory is now added to the PATH environment variable as a fallback when not_found_auto_install is enabled (which is the default behavior). This ensures that shims can handle tools that are not yet installed (triggering auto-install) and tools that exist on the system but are not managed by mise.
• Improved Auto-Install Behavior: This change addresses two unexpected behaviors of auto-install: preventing issues where subshells might not trigger installations for uninstalled tools, and ensuring the correct version is run even if a tool exists system-wide but isn't managed by mise.
• PATH Ordering: The shims directory is added after tool installation paths in the PATH, meaning installed tool versions take precedence, and shims act as a true fallback mechanism.

Changelog

• e2e/cli/test_activate_aggressive
  • Updated PATH assertions to include the shims directory when not_found_auto_install is true.
• e2e/cli/test_shims_fallback
  • Added a new end-to-end test to verify shims directory inclusion in PATH as a fallback.
  • Confirmed that shims appear after installed tool paths.
  • Verified shims are not in PATH when not_found_auto_install is false.
• src/toolset/toolset_paths.rs
  • Imported Settings and dirs modules for configuration and directory access.
  • Implemented logic in Toolset::get_path_env to conditionally append the shims directory to tool_paths if not_found_auto_install is enabled and the shims directory is not already present.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Copilot]

Pull request overview

Adds the shims directory to PATH (as a fallback, after installed tool paths) when not_found_auto_install is enabled, ensuring shims can trigger auto-install and avoid accidentally running unmanaged system binaries.

Changes:

• Append shims dir to tool PATH entries when not_found_auto_install is true.
• Add an e2e test validating shims are present/ordered and disabled when the setting is false.
• Update an existing e2e activation test to reflect the new PATH layout.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
src/toolset/toolset_paths.rs	Appends shims directory to tool paths when auto-install is enabled.
e2e/cli/test_shims_fallback	New e2e test covering shims presence, ordering, and opt-out behavior.
e2e/cli/test_activate_aggressive	Updates expected PATH output to include shims as fallback.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This method already takes a &Config, but the new behavior is gated by global Settings::get(). That mixes per-config behavior with global state and can make the resulting PATH depend on ambient settings rather than the provided config. Prefer reading the flag from config (if available) or pass the resolved boolean into this function so the result is deterministic and easier to test.

[Copilot]

This test validates presence and ordering of the shims dir in PATH, but it doesn't exercise the key behavior described in the PR: that the shim is actually used as a fallback to (a) trigger auto-install when the requested version isn't installed, and (b) avoid running an unmanaged system binary. Consider extending the e2e to run a command that must resolve via the shim (e.g., a tool with an existing shim but missing requested version) and assert that mise performs/attempts the auto-install rather than executing a system-provided binary.

[Copilot]

This test exports MISE_NOT_FOUND_AUTO_INSTALL=false but doesn't restore the previous value. If the e2e harness executes multiple tests in the same process/session, this can leak state into later tests. Consider saving the prior value and restoring it (or unsetting it) at the end of the test.

Suggested change

	# Shims should NOT be in PATH with not_found_auto_install=false
	export MISE_NOT_FOUND_AUTO_INSTALL=false
	eval "$(mise hook-env --force)"
	assert "[[ \"\$PATH\" != *\"$SHIMS_DIR\"* ]]"
	# Shims should NOT be in PATH with not_found_auto_install=false
	OLD_MISE_NOT_FOUND_AUTO_INSTALL="${MISE_NOT_FOUND_AUTO_INSTALL-__MISE_UNSET__}"
	export MISE_NOT_FOUND_AUTO_INSTALL=false
	eval "$(mise hook-env --force)"
	assert "[[ \"\$PATH\" != *\"$SHIMS_DIR\"* ]]"
	# Restore previous MISE_NOT_FOUND_AUTO_INSTALL value to avoid leaking state
	if [ "$OLD_MISE_NOT_FOUND_AUTO_INSTALL" = "__MISE_UNSET__" ]; then
	unset MISE_NOT_FOUND_AUTO_INSTALL
	else
	export MISE_NOT_FOUND_AUTO_INSTALL="$OLD_MISE_NOT_FOUND_AUTO_INSTALL"
	fi

[gemini-code-assist]

Code Review

This pull request enhances the auto-install feature by adding the shims directory to the PATH as a fallback. This is a great improvement that makes auto-installation more reliable, especially in subshells or when system-installed tools conflict with mise-managed versions. The implementation in toolset_paths.rs is clean and correct, and the new and updated e2e tests provide good coverage for the new behavior.

I have one suggestion to improve the robustness of the new test script e2e/cli/test_shims_fallback to prevent potential syntax errors during test execution.

[gemini-code-assist]

This check for path ordering can be made more robust.

1. If grep doesn't find a match, the position variable will be empty, leading to a syntax error in the assert command (e.g., [[ 10 -gt ]]). This can make debugging test failures tricky.
2. Using grep -n without -x or -F could lead to partial matches if a path happens to be a substring of another.

I suggest using grep -nFx for an exact, full-line match, and combining the presence and order checks into a single assertion. This prevents syntax errors and makes the test more reliable.

DUMMY_POS=$(echo "$PATH" | tr ':' '\n' | grep -nFx "$DUMMY_PATH" | cut -d: -f1)
SHIMS_POS=$(echo "$PATH" | tr ':' '\n' | grep -nFx "$SHIMS_DIR" | cut -d: -f1)
assert "[[ -n \"$DUMMY_POS\" && -n \"$SHIMS_POS\" && $SHIMS_POS -gt $DUMMY_POS ]]"

[jdx]

bugbot run

[jdx]

Note

This review was AI-generated using Claude Code.

Key concern: should this add shims or just not remove them?

The current flow is:

1. mise activate calls remove_shims() (src/cli/activate.rs:105) which strips the shims dir from PATH if present
2. PathEnv::from_iter (src/path_env.rs:62) also strips shims when it sees them
3. This PR then re-adds shims in list_final_paths_split as a "tool path"

This is working against the existing design rather than with it. The simpler and more correct approach would be: just don't remove shims from PATH when not_found_auto_install is true.

Specific concerns:

1. Conflicts with mise doctor diagnostics (src/cli/doctor/mod.rs:75-76)

mise doctor warns: "shims are on PATH and mise is also activated. You should only use one of these methods." This PR would cause that warning to fire for every default user, since shims would always be on PATH when activated with the default not_found_auto_install=true.

2. Round-tripping shims removal + re-addition is fragile

The activate script removes shims from PATH at shell init time (remove_shims() at activate.rs:154), then every hook-env re-adds them via the toolset paths. This means there's a brief window between activation and the first hook-env where shims aren't available. And the two pieces of code aren't aware of each other — they just happen to cancel out.

3. Shims end up classified as "tool paths" subject to dedup filtering

In build_path_operations (hook_env.rs:299), tool paths are filtered against __MISE_ORIG_PATH. If shims were in the original PATH before activation, they'd be filtered out of tool_paths, then... also removed from orig_path by PathEnv. The shims could disappear entirely.

4. Simpler alternative: just preserve shims

Instead of the add-back in toolset_paths.rs, modify remove_shims() in activate.rs and PathEnv::from_iter in path_env.rs to not strip shims when not_found_auto_install is true. The shims would naturally stay in their original position in PATH (likely after tool paths, since users typically put mise activate after adding shims). This is less code, fewer moving parts, and respects the user's original PATH ordering.

5. Test coverage gap

The new test_shims_fallback test installs dummy@1.0.0 and configures tiny = "3.0.0", but never actually tests that running a shim for an uninstalled tool triggers auto-install. It only checks PATH ordering. The core value proposition (subshells auto-installing missing tools) isn't verified.

Minor nits

• e2e/cli/test_shims_fallback:14 — tiny = "3.0.0" is configured but never used in the test
• The !tool_paths.contains(&shims_dir) guard is good but contains on Vec<PathBuf> won't catch canonical vs non-canonical duplicates (the same issue that build_path_operations handles with explicit canonicalization)

Recommendation

The "just don't remove shims" approach would be:

• In remove_shims(): skip removal when Settings::get().not_found_auto_install is true
• In PathEnv::from_iter: same condition — don't strip shims
• Update the mise doctor check to not warn when this is the intended behavior
• No changes needed in toolset_paths.rs

[ctaintor]

i agree your suggestion is much cleaner 😅 . Will come back with the suggestions

[ctaintor]

OK – I made those changes. I agree it's cleaner. I don't think it solves one issue though – but maybe you don't want to address that. I am using shims – so I can't say what the hook'd user's expectation is.

I believe that the hook'd mise will only install tools based on a tool not being found. This behavior is preserved by changing to "only stop removing shims." In other words, hook'd mise won't try to install a missing tool if the tool is present in the PATH already.

WIth this change, a user could have that experience if they manually added shims to their PATH before activating hook'd mise.

(Also, I might be misunderstanding how mise works!)