Last updated 13 October 2026
Protect git branches from Claude Code
The risk of automated commits to protected branches
When you run Claude Code in a terminal, you give an agent the power to execute commands in your shell. The agent uses the Bash tool to perform these actions. This means it can run git commands just as easily as it can run a build script or a test suite. If you do not set clear boundaries, the agent might commit changes directly to your main branch. This is a risk for any developer who values a clean production history and a standard pull request workflow.
The agent does not inherently know which branches are protected in your remote repository. It follows the instructions you provide and reacts to the state of the local file system. If you are currently on the main branch, the agent assumes that is where the work should happen. To protect your code, you must combine explicit instructions with restrictive tool settings and external safety checks. This ensures that the agent works within your existing git flow rather than bypassing it.
Establishing branch rules in CLAUDE.md
The most direct way to control the behavior of the agent is through the CLAUDE.md file. This file sits in your project root and provides context for every session. You should add a section titled Git Workflow to this file. In this section, clearly state that the agent is forbidden from committing directly to the main or master branches. Instruct the agent to always check the current branch using the Bash tool before starting any work or editing any files.
A well-defined CLAUDE.md file acts as a set of standing orders. You can tell the agent to create a new branch if it finds itself on main. Use a specific naming convention in your instructions, such as feature-description or bug-fix-id. When the agent understands that it must never touch main, it will start its sessions by running git checkout -b to move to a safe space. This simple text instruction is your first line of defense against accidental production changes.
Controlling execution with permission modes
Claude Code offers different levels of autonomy through permission modes. You can cycle through these modes by pressing Shift+Tab inside a session. The default mode asks for your permission before the agent uses any tool. This is the safest way to work because you must manually approve every git commit or git push command. If you see a command that targets a protected branch, you can deny the request or interrupt the agent by pressing the Escape key.
Avoid using the bypassPermissions mode on sensitive repositories. This mode allows the agent to run tools without asking for your consent. While it speeds up work, it removes the human review step that prevents direct commits to main. If you want to see what the agent plans to do without executing changes, use the plan mode. This allows the agent to think through the steps and show you the proposed git commands before any real action occurs on your disk.
Configuring tool restrictions in settings files
Detailed tool control lives in the settings.json file found in the .claude directory of your project. You can also apply these rules globally for all your work by editing ~/.claude/settings.json. Inside this file, the permissions key allows you to define how the agent interacts with specific tools. You can configure the Bash tool to require explicit approval even if you are using a more relaxed overall permission mode. This creates a specific safety gate for terminal commands.
By setting strict permissions for the Bash tool, you ensure that any attempt to run git push will trigger a confirmation prompt. This is helpful when you are deep in a coding session and might not notice the agent has switched its focus to deployment. You can use the /config command to view your current settings and ensure your local overrides are active. These settings stay with the project, providing a consistent safety layer for anyone running the claude command in that repository.
Using subagents for specific git tasks
You can create specialized subagents to handle your git workflow. These subagents are markdown files stored in the .claude/agents directory. You might create an agent named git-safety.md with instructions that focus entirely on branch management and protection rules. When you need to perform complex branch operations, you can call this agent using the /agents command. This keeps the logic for branch safety separate from your main coding instructions.
A git-specialist subagent can be programmed to run a series of checks before any push. It can verify the branch name, check for the existence of a pull request, or run a linting script. By delegating these tasks to a subagent, you reduce the risk of the main agent making an error in a busy terminal session. The subagent follows its own set of rules, which can be much more restrictive than your general project instructions.
Automating safety with hook events
Claude Code supports several hook events that trigger at specific points in a session. The PreToolUse hook is particularly useful for protecting branches. You can write a script that runs every time the agent tries to use the Bash tool. This script can check if the current command includes git push and verify the branch name. If the script detects an attempt to push to main, it can exit with an error, which stops the agent from proceeding.
These hooks are configured in your settings.json file. Using hooks provides a programmable way to enforce your team's workflow without relying on the agent to remember instructions. Because the hook runs before the tool is executed, it acts as a hard barrier. You can also use the PostToolUse hook to log every git command the agent runs, creating an audit trail of changes made during the session. This level of automation ensures that safety rules are always active.
Managing parallel branches with visual tiles
Working on multiple features at once increases the chance of a mistake. If you have several terminal tabs open, it is easy to run a push command in a session that is still on the main branch. adhdTerminal addresses this problem by organizing your work into a wall of tiles. Each Claude Code session is a tile with its own color, number, and name. You can designate a specific tile for your main branch work and others for feature branches, making the context clear at a glance.
The visual feedback from adhdTerminal shows whether a session is working, waiting for you, or idle. You can see the last exchanges of the conversation directly on the tile without clicking into it. This overview helps you verify the branch state before you provide the next task. Because tiles reopen in the same place after a restart and resume their sessions, you do not lose the context of which branch is which. This organization reduces the mental load of tracking multiple git states.
Monitoring git activity from any device
Long-running tasks can sometimes lead to unexpected git activity if the agent encounters an error and tries to fix it. adhdTerminal includes a free iPhone app that mirrors your terminal wall over an end to end encrypted link. This allows you to monitor the status of your git branches while you are away from your desk. You can see if a session has finished its work or if it is waiting for your permission to push a commit.
The mobile app allows you to answer a prompt or send the next task from your phone. If you see the agent asking for permission to commit to a branch you want to keep clean, you can deny the request immediately. This remote oversight ensures that your repository stays safe even when you are not actively typing at your computer. Having a live view of your terminal wall provides a final layer of security for your production code.
Questions people ask
What happens if the agent accidentally commits to the wrong branch?
You can use the Escape key twice to see a history of earlier messages and return to a point before the commit occurred. If the commit is already on your local disk, use the Bash tool to run a git reset command. Always use /review to check the changes the agent made before you allow it to push to a remote repository.
Can I prevent the agent from using the Bash tool entirely?
Yes, you can restrict the Bash tool in your settings.json file under the permissions key. You can set it to a denied state or require manual approval for every single call. This is the most restrictive setting and ensures the agent can only read or edit files without running terminal commands.
Does Claude Code respect my global git configuration?
Yes, the agent uses the standard git installation on your system through the Bash tool. It will respect your global .gitignore file, your branch protection rules on the server, and any local git hooks you have configured in the .git/hooks directory. If a server-side rule blocks a push to main, the Bash tool will return an error and the agent will stop.
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.