Git Extension for Pi Coding Agent

Comprehensive git workflow automation for pi, focusing on worktree management, smart rebase/fixup workflows, and other common git tasks.

Features

Phase 1: Worktree Management ✅

Manage git worktrees easily without cluttering your repository with multiple checkouts.

Commands:

• /worktree list or /wt ls - List all worktrees with status
• /worktree create <branch> or /wt new <branch> - Create worktree for branch
• /worktree remove <branch> or /wt rm <branch> - Remove worktree
• /worktree prune - Clean up stale worktree references

Tool:

• git-worktree - AI can manage worktrees programmatically

Upcoming Features

• Phase 2: Smart rebase/fixup workflows
• Phase 3: Commit helpers and validation
• Phase 4: Branch management
• Phase 5: Integration and polish

Installation

The extension is automatically loaded from ~/.config/pi/agent/extensions/git/.

To enable:

cd ~/src/home/dots
make pi-agent

Usage

List Worktrees

/worktree list
/wt ls

Shows all worktrees with:

• Branch name (with dirty indicator *)
• Path
• Current commit
• Status (locked, prunable)
• Current worktree indicator ➜

Create Worktree

/worktree create feature-branch
/wt new bugfix-123

Creates a worktree in .worktrees/feature-branch relative to repository root.

With custom path:

/worktree create feature-x /tmp/feature-x

Behavior:

• If branch exists locally: Creates worktree for that branch
• If branch exists on origin: Creates local branch tracking origin
• If branch doesn’t exist: Creates new branch

Remove Worktree

/worktree remove feature-branch
/wt rm bugfix-123

Safety:

• Checks for uncommitted changes
• Prompts for confirmation if changes exist
• Use force flag in tool for bypassing

Prune Worktrees

/worktree prune

Cleans up stale worktree administrative files.

Tool Usage (for AI)

The extension registers a git-worktree tool that AI agents can use:

{
  name: "git-worktree",
  action: "list" | "create" | "remove",
  branch: "branch-name",      // For create/remove
  path: "/custom/path",        // Optional for create
  force: true                  // Optional for remove
}

Examples:

List worktrees:

{
  "action": "list"
}

Create worktree:

{
  "action": "create",
  "branch": "feature-x"
}

Remove worktree:

{
  "action": "remove",
  "branch": "feature-x",
  "force": false
}

Worktree Directory Structure

Worktrees are created in .worktrees/ subdirectory:

~/src/home/
├── .git/
├── .worktrees/
│   ├── feature-a/      # Worktree for feature-a branch
│   ├── bugfix-123/     # Worktree for bugfix-123 branch
│   └── experiment/     # Worktree for experiment branch
├── systems/
├── home/
└── ...

Why .worktrees/?

• Keeps worktrees organized in one place
• Easy to gitignore (add .worktrees/ to .gitignore)
• Clear separation from main repository
• All worktrees easy to find and manage

Best Practices

When to Use Worktrees

Good for:

• Working on multiple features simultaneously
• Keeping long-running branches checked out
• Testing changes without switching branches
• Code review without disrupting current work

Not good for:

• Quick branch switches (just use git switch)
• Temporary experiments (use git stash instead)

Worktree Workflow

1. Create worktree for feature:

   /wt new feature-x
   cd .worktrees/feature-x
   

2. Work in worktree:

   # Make changes, commit, push
   git add .
   git commit -m "feat: add feature x"
   git push origin feature-x:feature-x
   

3. Switch back to main:

   cd ~/src/home
   # Main worktree is unaffected
   

4. Clean up when done:

   /wt rm feature-x
   

Multiple Worktrees Pattern

Working on frontend and backend simultaneously:

/wt new frontend-feature
/wt new backend-feature

# Terminal 1
cd .worktrees/frontend-feature
# Work on frontend

# Terminal 2  
cd .worktrees/backend-feature
# Work on backend

# Main terminal
cd ~/src/home
# Work on main branch or review

Configuration

No configuration needed for Phase 1. Future phases will add configuration options in .pi/config.json.

Troubleshooting

Error: “Not in a git repository”

Make sure you’re running commands from within a git repository.

Error: “Worktree path already exists”

The worktree directory already exists. Either:

• Remove it manually: rm -rf .worktrees/branch-name
• Use a different path: /wt new branch-name /tmp/branch-name

Error: “Worktree has uncommitted changes”

The worktree has uncommitted changes. Either:

• Commit the changes
• Use force removal (will be prompted)
• Manually handle: cd .worktrees/branch-name && git stash

Stale Worktree References

If you manually deleted a worktree directory, git may still have references:

/worktree prune

Technical Details

Implementation

• Language: TypeScript
• Location: dots/pi/agent/extensions/git/
• Modules:
  • index.ts - Main extension entry, command/tool registration
  • worktree.ts - Worktree management logic
  • utils.ts - Git utility functions
  • types.ts - TypeScript type definitions

Dependencies

• Git >= 2.30 (for improved worktree support)
• Node.js/Bun for TypeScript execution

Error Handling

All operations include:

• Input validation
• Git repository detection
• Uncommitted changes detection
• Clear error messages
• Safe defaults

Roadmap

Phase 2: Smart Rebase/Fixup (Next)

• /fixup <commit> - Create fixup commit
• /rebase-fixups - Auto-squash fixups
• Pre-push fixup detection

Phase 3: Commit Helpers

• /commit - Interactive conventional commit
• Commit message validation
• AI-assisted commit messages

Phase 4: Branch Management

• /branch list - List branches with info
• /branch cleanup - Remove merged branches

Phase 5: Polish

• Comprehensive error handling
• Configuration system
• Full documentation

Related

• Plan: ~/.local/share/ai/plans/pi-git-extension.md
• Research: ~/.local/share/ai/research/2026-02/2026-02-06-git-rebase-fixup-best-practices.md

License

Part of vdemeester/home repository.