@jocax/git-workflow0.2.2

@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

Command	What it does
/git-wf snapshot <msg>	Runs git add -A and git commit -m "snapshot: <msg>" in the command, not in an agent turn
/git-wf status	Shows branch, dirty count, stash count, last 10 commits
/git-wf branches	Lists local branches with current-branch marker
/git-wf stash-pop	Pops the most recent auto-stash (if it matches)

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.

Step	Do this	Watch
1	Send the first prompt	The agent edits src/greet.js; nothing is stashed yet — the tree was clean when the turn began
2	Send the second prompt	At the turn's start: 📦 Git Workflow: Auto-stashed 1 file(s). The agent re-reads the file and sees the baseline text, because its change is in the stash
3	Let the turn end	📦 Git Workflow: Auto-stash restored.
4	Type /git-wf status	Branch, dirty count, stash count and the recent commits

Scenario "The git-wf subcommands"

Step	Do this	Watch
1	Send the first prompt	The agent creates feature/greeting with git
2	Type /git-wf branches	Both branches, the current one marked ●
3	Send the second prompt	The agent edits src/greet.js to note the branch
4	Type /git-wf stash-pop	No stashes to pop. — the tree was clean when this turn began, so nothing was auto-stashed
5	Type /git-wf snapshot wip	📸 Snapshot committed: "snapshot: wip", followed by git's own output: a [feature/greeting <sha>] snapshot: wip summary line, a one-time warning about an automatically configured committer identity (it names your own name and host — the sandbox repo has none of its own), and 1 file changed, 1 insertion(+)
6	Type /git-wf status	Branch: feature/greeting, Dirty: 0 file(s), Stashes: 0, and snapshot: wip at the top of the recent commits, above Sandbox baseline
7	Type /git-wf snapshot wip again	📸 Nothing to snapshot — the working tree is clean. — the commit above already took everything
8	Type /git-wf with no argument	Prints the same status block as /git-wf status

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