branch-lock

Locks the agent to a git branch and blocks branch-switching commands via pre-tool hooks.

20|2|Updated May 16, 2026
One-click install
npx skills add https://github.com/reddb-io/red-skills --skill branch-lock-reddb-io
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: branch-lock
Source: https://github.com/reddb-io/red-skills/tree/main/plugins/dev/skills/misc/branch-lock
Command: npx skills add https://github.com/reddb-io/red-skills --skill branch-lock-reddb-io

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve? Agents can accidentally switch branches, stash work, or run destructive git commands in the primary checkout, destroying in-progress work. This Skill pins the agent to one branch and enforces the lock through self-contained pre-tool hooks. ## Core Features & Use Cases - Branch Locking: Set, change, or clear a branch lock through the bundled CLI, which performs an atomic relock-then-switch so the hook never blocks the requested change. - Pre-Tool Hook Enforcement: Claude Code PreToolUse(Bash) and Codex plugin hooks intercept git checkout, switch, stash, clean -f, reset --hard, and whole-tree restore commands in the primary checkout. - Unconditional Primary Guard: Once the dev plugin is enabled, the agent can never move the primary checkout's branch, while isolated worktrees under .red/tmp/ lanes stay exempt. - Use Case: During a long autonomous session on a feature branch, run /branch-lock to guarantee the agent stays on that branch and cannot shelve or discard the human's parallel WIP in the main checkout. ## Quick Start Ask the agent to lock itself to the current branch by running the branch-lock CLI set command, then confirm the lock with the status action.

Frequently Asked Questions about branch-lock

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I lock an AI agent to a git branch?▼

Run the branch-lock CLI with the set action and a branch name, or invoke the /branch-lock command with no argument to lock to the current branch. The CLI atomically rewrites the lock target before switching, so the hook never blocks the requested change.

How to prevent an agent from switching branches in Claude Code?▼

Enable the dev plugin, which registers a PreToolUse hook for Bash that blocks git checkout and git switch in the primary checkout. The guard is unconditional once plugins.dev.enabled is true and needs no per-repo settings copy.

Does branch-lock work with Codex CLI?▼

Yes, the dev plugin ships a Codex hook manifest that reads PreToolUse payloads and reuses the same lock-store and git-command-classifier modules. Codex must load the updated plugin and have plugin hooks enabled, which older builds may require setting plugin_hooks to true in config.toml.

What git commands does the branch-lock hook block?▼

The hook blocks git checkout, git switch, git stash push, git clean with force flags, git reset --hard, and whole-tree restores in the primary checkout. It allows targeted file restores, read-only stash and clean dry-runs, soft resets, commits, and worktree creation in registered lanes.

Can branch-lock stop a human from switching branches in the terminal?▼

No, enforcement is agent-only by design per ADR 0006. The hooks intercept the agent's own tool calls through Claude Code and Codex pre-tool mechanisms, not the human's terminal session.

Why is my branch lock not enforced in Codex?▼

The lock file may exist but Codex will not enforce it if plugin hooks are disabled. Check that Codex loaded the updated dev plugin and that plugin_hooks is enabled, which older builds require in ~/.codex/config.toml.