Try free

Last updated 13 October 2026

Force Claude Code to use a specific shell

Identifying shell environment mismatch issues

When you start a session with Claude Code, the agent needs a way to communicate with your operating system to execute commands and read files. It accomplishes this by running a shell. Most developers have a carefully tuned shell environment with specific paths, aliases, and custom functions that make their daily workflow possible. If the agent defaults to a basic version of Bash when you normally use a feature-rich Zsh setup, you will run into friction immediately. You might ask it to run a build command only to have it fail because a certain environment variable or a specific version of a tool is missing from the agent's view.

When the agent tries to run a command, it relies on the underlying shell to interpret the syntax. If you are using Zsh features like advanced globbing or specific array behaviors, a standard Bash shell will return syntax errors. This mismatch can be frustrating because the code you see in your editor looks correct, but the agent cannot execute the scripts you provide. Understanding how to force the agent to use your preferred shell is essential for a smooth development experience. It allows you to move away from generic commands and use the full power of your existing terminal environment and its custom configurations.

Modifying the global configuration file

Global configuration is the first place to look when you want to change how the agent behaves across all your projects. You can find your user settings in a file located at ~/.claude/settings.json. This file allows you to define the default behavior for the agent regardless of which directory you are working in. To force a specific shell, you should look for the entry that specifies the shell executable path. By pointing this to the full path of your preferred shell, such as /bin/zsh or /usr/local/bin/bash, you ensure that every new session starts with the environment you prefer.

Editing ~/.claude/settings.json requires a basic understanding of its structure. You will find various keys that control the agent's permissions and its interaction with tools. When you add the entry for the shell path, you must provide a valid string that the operating system can resolve. If you use a version of a shell installed via a manager like Homebrew, the path will likely be different from the system default found in /bin. Taking the time to locate the exact path using a command like which zsh before you update your settings file will prevent the agent from failing to start due to a missing executable.

Project level shell overrides

Sometimes a single global setting is not enough because different projects have different requirements. You might have a legacy project that requires an older version of Bash or a specific Windows project where PowerShell is the only viable option. In these cases, you can place a .claude/settings.json file directly in the root of your project repository. The agent looks for this file whenever you run the claude command in that folder. This local configuration overrides your global settings, allowing you to tailor the shell environment to the specific needs of the code base.

Project-specific settings are particularly useful when collaborating with other developers who might have different local environments. By including a .claude/settings.json file in your repository, you establish a baseline for how the agent should interact with the project's build system. If you need to make changes that are specific to your machine and should not be shared with your team, you can use .claude/settings.local.json instead. This file is the perfect place for paths and shell overrides that only exist on your local drive and should not be tracked by git.

Leveraging terminal setup for environment parity

Ensuring the agent understands your shell environment goes beyond just naming the executable. You often need the agent to be aware of your aliases and local scripts. The /terminal-setup slash command is designed for this purpose. When you run this command inside a session, the agent performs a check of your current terminal environment. It looks at your PATH and other environment variables to build a profile of what is available. This helps prevent situations where you know a tool is installed but the agent claims it cannot find it.

The agent often relies on its initial environment scan to determine what it can and cannot do. If your shell startup scripts modify the PATH variable to include directories for language runtimes, the agent needs to see those changes. Running /terminal-setup triggers a re-evaluation of these variables. This is more than just a refresh; it is a way for the agent to learn the nuances of your specific setup. It is a good habit to run this command whenever you enter a new environment or feel like the agent is missing context about your installed software.

Managing tool execution through the Bash tool

The primary way the agent interacts with your system is through the Bash tool. Even if you are using a different shell as your primary interface, the agent uses this tool to execute commands and gather output. It is important to understand that the agent effectively opens a new shell instance for the tasks it performs. If your shell configuration files are slow to load or have interactive prompts, it can interfere with the agent's ability to work efficiently. You should ensure that your shell startup scripts are non-interactive when a command is passed directly to them.

When the Bash tool is active, it creates a bridge between the agent's logic and your machine's capabilities. This tool is versatile, but it is not a perfect mirror of a human-controlled terminal session. For example, it might not automatically load your full shell history or every single alias unless the shell is configured to do so for non-interactive sessions. If you find that the agent is struggling to find your custom shell functions, moving critical aliases or functions from a purely interactive config file to one that is sourced more broadly can help the Bash tool perform its duties more effectively.

Using project instructions for shell guidance

You can also provide specific instructions to the agent regarding shell usage within the CLAUDE.md file. This file sits in your project root and serves as a guide for how the agent should operate within that specific repo. If there are certain shell commands that must be run with specific flags or in a specific order, you can document them here. For example, you can tell the agent to always use a specific shell syntax when writing scripts or to favor certain shell built-ins over external commands.

Using CLAUDE.md for shell guidance provides a persistent source of truth for the agent. While settings files handle the technical configuration of which shell to launch, CLAUDE.md handles the logic of how to use it. You can specify that the agent should always check the exit code of a command in a specific way or that it should use certain shell flags to ensure output is formatted correctly. This is also a great place to warn the agent about known issues with certain shells in your environment. Documenting these nuances ensures the agent can work around them.

Parallel shell management with adhdTerminal

When you are managing multiple projects with diverging shell needs, a single terminal window can become a bottleneck. This is where adhdTerminal becomes a useful part of your workflow. It allows you to run many Claude Code sessions side by side on a wall of tiles. Each tile can represent a different project with its own shell configuration. You can have one tile dedicated to a project running in a Zsh environment while another tile next to it handles a project that requires a specialized Bash setup. This physical separation of environments helps you stay organized without constantly editing your settings files.

The tile-based interface of adhdTerminal makes it easy to visualize these different environments. You can name each tile based on the shell or project it is using, which provides a clear map of your active work. Because adhdTerminal reopens your tiles in the same place and resumes the same session after a restart, you do not have to worry about reconfiguring your shell environment every time you switch tasks. Each tile remembers its state, which is a powerful way to manage the complexity of modern development where you often context switch between different stacks.

Verification and troubleshooting

If you suspect your shell configuration is not being applied correctly, there are several ways to verify the environment. You can ask the agent to run a simple command like echo $SHELL or use the which command to find the path of the shell it is currently using. This gives you immediate feedback on whether your changes in .claude/settings.json have taken effect. Additionally, the /doctor command is available to check the overall health of your installation and identify issues with your path or permissions that might be preventing your chosen shell from launching correctly.

Troubleshooting is an iterative process. If your shell settings seem to be ignored, verify that there are no syntax errors in your json files that might be causing the agent to fall back to defaults. You can also use the /config command within a session to inspect the current state of your settings. This command provides a view of what the agent believes its configuration to be at that moment. By comparing the output of /config with the contents of your settings files, you can identify where the discrepancy lies. If all else fails, a fresh start using the /clear command can resolve environment issues.

Questions people ask

How can I tell which shell the agent is using right now?

You can use the Bash tool to run the command echo $0 or echo $SHELL inside the session. This will return the path of the executable currently interpreting the agent's commands. Comparing this to your expected path helps confirm your settings are active.

Can I use different shells for different sessions in the same folder?

Since settings are usually tied to the folder via .claude/settings.json, you would need to use .claude/settings.local.json or manually edit the file to switch. Alternatively, using adhdTerminal allows you to keep different sessions open in separate tiles with their own persistent states and environments.

What if I am on Windows and want to use PowerShell instead of Bash?

You must update your settings.json file to point to the path of the powershell.exe or pwsh.exe binary. Once updated, the agent will use that environment for its command execution tasks. Ensure your scripts are compatible with PowerShell syntax before making this switch as the agent defaults to Unix-style commands otherwise.

Read next

More on claude code basics·All posts