Last updated 13 October 2026
Use Claude Code with a specific git branch
Use Claude Code with a specific git branch
When you launch Claude Code by typing claude in your terminal, the agent initializes by scanning your current working directory. It respects your .gitignore file and understands it is operating within a git repository. If you are already on a specific feature branch, the agent will see the files as they exist on that branch at that exact moment. It uses tools like Glob and Read to build an initial understanding of the project structure and the files available for the task you have in mind.
If you need to work on a specific branch, the most reliable method is to check out that branch in your terminal before you start the session. Claude Code does not have a dedicated slash command to switch git branches because it expects you to manage your version control state using standard git commands in your shell. Once you are on the correct branch, running the claude command ensures the agent starts with the correct file context. This prevents the agent from reading outdated files or making changes to the wrong version of your code.
Changing branches during an active session
You might realize mid-conversation that you are on the wrong branch or need to pull the latest changes from a remote repository. You can switch branches while the agent is waiting for your input by using git checkout or git switch in your terminal. Since the agent uses the local file system as its source of truth, any changes made by these git commands will be visible to the agent's tools. However, the agent's internal memory of files it has already read might become outdated if those files changed significantly during the branch switch.
To keep the agent synchronized after a branch change, you should inform it about the switch in plain language. You can simply type a message telling the agent that you have switched to a different branch. This prompts the agent to use the Read tool again if it needs to verify the current state of the code. If the branch switch involved many file changes, the agent's previous context might contain irrelevant information from the old branch. Explicitly mentioning the branch name helps the agent adjust its mental model of the codebase.
Managing context after a branch switch
The conversation history in a Claude Code session stays active even if you change the underlying files. This can be problematic if the agent tries to reference code logic that no longer exists on the new branch. You can use the /compact command to summarize the current session. This reduces the token count of the conversation while keeping the essential goals and progress in the context window. It helps the agent focus on the current task without getting confused by deleted or moved functions from the previous branch.
If the branches are entirely different and you want to start fresh without closing the terminal, the /clear command is a useful option. This command wipes the current conversation history in that folder but keeps the agent running. It acts as a reset for the agent's memory of the current session. Use this when you move from a bug fix branch to a new feature branch and you do not want any logic from the fix to influence the feature development. This ensures that the agent does not try to use variable names or architectural patterns that are not present in your current branch.
Resuming sessions on different branches
Claude Code allows you to resume previous sessions using the claude --resume command. This command presents a list of your past interactions so you can pick up where you left off. When you resume a session, the agent expects the file system to be in a state compatible with that session. If you resume a session that was started on a feature branch while your terminal is currently on the main branch, the agent might get confused when its tools return file contents that do not match its remembered history.
For developers who frequently jump between many branches, adhdTerminal provides a visual way to handle this complexity. It runs many Claude Code sessions side by side, each one a tile on a wall. A tile has a colour, a number and a name, shows whether it is working, waiting for you, done or idle, and shows the last exchanges of its conversation. Tiles reopen in the same place after a restart and resume the same session, so you do not have to constantly use the resume command or manually switch branches in a single terminal window.
Branch specific instructions with CLAUDE.md
You can guide the agent's behavior on specific branches by using the CLAUDE.md file. If your project has a different build command or test suite for a specific branch, you can update the CLAUDE.md file in the repository root to reflect these changes. The agent reads this file to understand project norms and available commands. Since this file is part of your repository, it changes when you switch branches. This is an effective way to ensure the agent always uses the correct environment settings for the branch you are currently working on.
If only a specific part of your project tree needs special instructions for a branch, you can place a CLAUDE.md file in a subdirectory. The agent prioritizes instructions in the current subdirectory over those in the root. This is particularly useful for monorepos where different branches might focus on different services or libraries. By tailoring these files, you ensure the agent uses the correct Bash commands and follows the right coding standards for the specific code it is touching on that branch.
Handling conflicts and file changes
When you switch branches and find yourself in a merge conflict, Claude Code can help resolve it. You can ask the agent to look at the conflict markers in the files. The agent can use the Read tool to see both the HEAD changes and the incoming changes. You can then ask it to resolve the conflicts based on the context of the project. The agent will use the Edit or Write tools to modify the files and remove the conflict markers once the logic is unified.
Be careful when using permission modes like bypassPermissions during a complex branch merge. It is safer to use the default mode or acceptEdits mode so you can review each change the agent makes to the conflicting files. You can cycle through these modes inside a session by pressing Shift+Tab. This ensures that the agent does not accidentally overwrite important logic while trying to clean up git conflict symbols in your source code. If a change looks wrong, you can press Escape twice to go back to an earlier message.
Monitoring state and remote activity
Switching branches often involves running fresh builds or tests to ensure everything is working as expected. You can monitor the agent's activity and the resulting costs using the /cost and /usage commands. If a branch switch causes the agent to re-read a large portion of the codebase, your token usage will increase. Keeping an eye on these stats helps you decide when it is time to use /compact or /clear to manage your context window and your budget.
If you use the adhdTerminal app, you can mirror your wall to your iPhone over an end-to-end encrypted link. The free iPhone app shows whether a session is working, waiting for you, done or idle. If the agent is running a long test suite after a branch merge on your computer, you can see the progress on your phone and can even answer a prompt or send the next task while away from your desk. This allows you to maintain momentum on branch-heavy projects without being tied to your workstation.
Configuring branch behavior in settings
You can customize how Claude Code interacts with your files across different branches by modifying .claude/settings.json. This file can be used to define specific permissions for tools on a project-wide basis. If a specific branch requires more restrictive access to certain directories, you can adjust the permissions settings in this file. The agent will respect these settings regardless of which branch you are on, as long as the .claude directory is present in your current working tree.
For personal overrides that you do not want to commit to the repository, use .claude/settings.local.json. This is useful if you have a specific workflow for branch switching that involves local scripts or MCP servers that are not shared with the rest of the team. By keeping your local configuration separate, you maintain a consistent environment for the agent across all your local git branches without affecting the project configuration for other developers. You can also set global preferences in your home directory at ~/.claude/settings.json.
Advanced automation with hooks
Claude Code supports several hook events that can be triggered during a session, such as SessionStart or UserPromptSubmit. While these hooks cannot directly change your git branch, you can use them to run custom scripts that log the current branch name or verify that the agent is working in the expected environment. This adds a layer of safety to your workflow. For example, you could configure a hook to run a script that checks the current git branch every time you submit a prompt.
If the branch name does not match a specific pattern, the script could output a warning that the agent sees in its terminal environment. This helps prevent situations where you accidentally ask the agent to make changes to the main branch when you intended to be on a feature branch. Using these hooks effectively makes your branch-based development more predictable. You can also use the /hooks command to see which hooks are currently active and ensure your safety scripts are running as intended.
Questions people ask
Does Claude Code automatically switch branches?
No, Claude Code does not manage your git branches for you. You must use the standard git checkout or git switch commands in your terminal to change the working directory state. The agent will then see the updated files when it uses its Read and Glob tools.
What happens if I switch branches while the agent is mid-task?
The agent might get confused if the files it is currently editing change or disappear. It is best to interrupt the agent with the Escape key before switching branches. Once the switch is complete, use the /status command or tell the agent about the change so it can refresh its understanding of the code.
How can I keep different branch contexts separate?
The most effective way is to use /clear when moving between unrelated branches in the same terminal session. Alternatively, using adhdTerminal allows you to keep multiple sessions open in different tiles, each tied to a specific branch, which prevents the agent's memory of one branch from affecting its work on another.
Read next
- Add build instructions to your CLAUDE.md fileImprove project context by adding specific build commands and environment requirements to your CLAUDE.md file for the AI to follow.
- Add common error fixes to CLAUDE.mdImprove project memory by adding a section for common errors and their fixes to your CLAUDE.md configuration file.
- Add custom shell aliases for Claude CodeSpeed up your workflow by creating shell aliases for common Claude Code invocations and project-specific startup commands.
- Add test commands to a CLAUDE.md fileUnderstand how to define specific test runners and environment flags in your CLAUDE.md file so the tool runs the correct test suite.