@jocax/git-workflow

Git workflow automation for pi agent turns — protects uncommitted work with auto-stash, provides quick slash commands for common git operations, and guards against destructive git commands.

What

This pi extension automates the friction points between manual development and agent-driven git operations:

• Auto-stash — Before each agent turn in an interactive session, stashes your uncommitted changes so the agent can safely run git checkout, git merge, or git rebase without conflicts.
• Smart restore — Optionally auto-pops the stash after the agent finishes, but only if the agent didn't create its own stashes.
• Slash commands — Quick access to status, branches, snapshots, and stash management from within pi.

Why

When pi agents run git operations, they don't know about your uncommitted work. A single git checkout other-branch can fail or lose changes. Auto-stash solves this automatically.

The slash commands replace typing manual git commands:

• /git-wf status instead of git status && git log
• /git-wf snapshot "wip" instead of git add -A && git commit -m "wip"
• /git-wf branches instead of git branch -v

Install

Install the package from npm:

{
  "source": "npm:@jocax/git-workflow"
}

Or try it from a local checkout without installing:

pi -e ./src/index.ts

Usage

Once installed, the extension auto-stashes your dirty files before every agent turn you drive yourself. You'll see a notification when it activates.

Commands

Auto-Stash Flow

Your dirty files → Agent turn starts → Auto-stash → Agent runs git ops
                                   → Agent finishes → (optional) Auto-pop

• Auto-stash: Enabled by default. Set AE_PI_GIT_WORKFLOW_AUTO_STASH=false to disable.
• Auto-pop: Disabled by default (safe). Set AE_PI_GIT_WORKFLOW_AUTO_POP=true to enable.
• Smart detection: If the agent creates its own stashes during a turn, auto-pop skips to avoid losing the agent's work.

Where the stash does not run

Auto-stash protects a person's uncommitted work, so it runs only in a session someone is driving. It skips a turn when either of these is true:

• pi reports no dialog-capable UI — print and JSON mode (pi -p, --mode json), which is how every headless driver runs pi.
• ae-adws launched the session — the framework marks every agent it spawns with AE_ADWS_HARNESS in the environment.

In a framework-launched turn the dirty tree is not work in progress, it is the hand-off to the next agent: an ADW planner leaves a spec behind for the committer to pick up. Stashing it deletes that hand-off, and the next agent finds nothing to commit. Nothing is stashed there, so the artefact survives the turn boundary.

An RPC-driven session (a demo or an editor plugin with a human at the other end) still counts as interactive and still stashes.

If an earlier version of this extension stashed an artefact you meant to keep, /git-wf stash-pop restores the most recent auto-stash.

Configuration

# Disable auto-stash in every session, including interactive ones (default: enabled)
export AE_PI_GIT_WORKFLOW_AUTO_STASH=false

# Enable auto-pop after agent turns (default: disabled)
# Restores only the stash this extension pushed, identified by its message
# after git's "On <branch>: " prefix. Skips if the top stash is someone else's.
export AE_PI_GIT_WORKFLOW_AUTO_POP=true

# Custom stash message prefix (default: "ae-pi:git-wf auto-stash")
export AE_PI_GIT_WORKFLOW_STASH_MESSAGE="my-project auto-stash"

Recommended Pairing

Install alongside @jocax/security-guard for complete git safety:

• git-workflow handles automation (stash, status, snapshot)
• security-guard handles blocking (force push, hard reset, clean)

Run the demo

just demo-web git-workflow     # browser
just demo git-workflow         # herdr

A sandbox copy always starts on a clean baseline commit, and the stash hook fires at the start of an agent turn. So the first turn is what makes the tree dirty and the second turn is where the stash happens.

Scenario "Auto-stash and restore" — runs with AE_PI_GIT_WORKFLOW_AUTO_POP=true, so both halves show in one run.

Scenario "The git-wf subcommands"

This package decides nothing per tool call, so it has no block to show. A blocked git reset --hard is a security-guard rule — see security-guard.

Needs herdr 0.9.3 or newer and one reachable model provider — see demo-kit.

Development

# Try it locally
pi -e packages/git-workflow/src/index.ts

# Check status
/git-wf status

# List branches
/git-wf branches