Machine Branch

An opinionated Codex branch workflow guard that automatically moves non-trivial work to a safer local branch after installation.

Machine Branch is a standalone Codex skill with one clear job: inspect the current git state before non-trivial work, decide whether the task belongs in the current branch, and automatically create or switch to a safer local branch when the repo is installed and git state is safe.

What It Does

• checks the current branch, status, diff stats, and recent commits
• warns when non-trivial work is happening in main or master
• creates or switches to a safer local branch by default after installation
• refuses to switch when the worktree is mixed or git is in an unsafe state
• speaks in the user's language and can stay fully in Russian for Russian chats
• tells you to split work when the current changes look mixed
• never pushes, merges, force-pushes, deletes branches, or changes remote state silently

Who It Is For

• beginners who want safer Git defaults without a Git lecture
• vibe-coders who want Codex to keep work out of main
• solo builders who do not want to mix multiple tasks in one branch
• Codex users who want automatic local branch hygiene before risky implementation

Install In Codex

Ask Codex:

Use $skill-installer to install https://github.com/harnessmachine/machine-branch/tree/main/skills/machine-branch

Manual install:

cp -R skills/machine-branch ~/.codex/skills/

Restart Codex after installation.

First Use In A Repo

The first explicit use in a repository can bootstrap the repo-level guard:

Use $machine-branch to check this branch decision.

If the repo is not set up yet, Machine Branch asks whether to install the guard now. If you say yes, it:

• ensures .agents/skills/machine-branch/ exists in that repo
• patches the repo root AGENTS.md so Codex calls $machine-branch before non-trivial work
• enables automatic local branch switching by default

There is no second opt-in prompt for auto-switching. Installing the guard is the repo-level opt-in. You can later disable local auto-switching by asking Codex to disable Machine Branch auto-switch for that repo.

What Happens During Runtime

After the repo is set up, Machine Branch quickly inspects the current git state and answers with a short decision:

• stay on current branch
• create a new branch
• split current work
• ready to commit
• ready for PR later

When a new branch is better and auto-switching is enabled, it creates or switches to the recommended local branch automatically if git state is safe.

It stops instead of switching when the worktree looks mixed, HEAD is detached, a merge/rebase/cherry-pick/revert/bisect is in progress, or repo/user instructions explicitly forbid automatic branch switching.

What It Does Not Do Automatically

• push changes
• open pull requests
• merge branches
• force-push
• delete branches
• change remote state silently
• override explicit user or repo instructions that forbid automatic branch switching

Example Output

### Machine Branch
One-line decision: create a new branch

### why
- You are in `main`.
- This task is larger than a tiny safe edit.
- I will move it to a separate local branch so the main line stays clean.

### do this now
auto-switch: enabled
planned branch: feature/auth-form-cleanup

Repository Layout

• skills/machine-branch - the installable skill
• README.md - English overview
• README.ru.md - Russian overview

Why It Helps

• keeps main and master cleaner
• reduces accidental mixed branches
• makes review and rollback easier
• gives safe branch hygiene without slowing normal work

License

MIT