pi-posh-git

A posh-git style persistent git status footer for pi — plus a note + git status feed injected into the agent context.

Inspired by dahlbyk/posh-git — the excellent PowerShell module that pioneered rich git status in the prompt.

It does two things:

• Footer (UI) — branch, ahead/behind, staged/unstaged counts, and stash count, always visible on the right side of the pwd line. Replaces pi's built-in footer branch display to avoid duplication. No commands needed.
• Context feed (LLM) — a timestamped note plus a compact one-line git status, injected at startup, on every turn, and whenever the note file changes — so the agent is no longer blind to your scratchpad or branch state. See Note + git context feed.

Install

pi install npm:pi-posh-git

Or add manually to your pi settings.json:

{
  "packages": ["npm:pi-posh-git"]
}

What it looks like

Git status appears on the right side of the pwd line in the footer:

~/projects/app [main ↑3 +1 ~0 -0 | +0 ~2 -0 !]

Element	Symbol	Meaning
Brackets	[ ]	Yellow
Branch	main	Cyan/accent
Identical	≡	Up to date with remote
Ahead	↑3	3 commits ahead
Behind	↓2	2 commits behind
Diverged	↓2 ↑3	Behind & ahead
Gone	×	Upstream deleted
Staged	+1 ~2 -0	Green (index changes)
Delimiter	|	Yellow separator
Unstaged	+0 ~1 -0	Red (working tree)
Clean	(none)	No local-status symbol when working tree and index are clean
Staged only	~	Cyan
Dirty	!	Red
Stash	(3)	Stash count

Auto-refreshes on session start and after every tool execution.

Footer integration

The extension replaces pi's built-in footer with a custom one that shows the same information (pwd, token stats, context usage, model name) with the git status appended to the right side of the pwd line. The built-in footer is automatically restored when the session shuts down.

Note + git context feed

The agent is no longer blind to your scratchpad or branch state. pi-posh-git feeds a timestamped note (plus a compact, colorless git status) into the LLM context:

[pi-posh-git note · 2026-03-30T18:42:11+02:00 · project]
git: note ↑1 +0 ~1 -0 !

Ship via tag only — never npm publish from the laptop.

The git line mirrors posh-git's symbols (≡ ↑ ↓ × | ! ~) so it stays recognizable next to the colored footer, with the same getGitStatus call shared between the two (cached per turn so the footer and the feed never spawn git twice).

Event	Action
Session start	Read note + git → inject (nextTurn, no wake)
Note file change	Re-read → inject with new timestamp (silent by default)
Every agent turn	Attach current payload via before_agent_start
After tools / turn end	Refresh git quietly (picked up on next turn)
Context build	Drop all but the newest pi-posh-git-note message

/note command

Command	Action
/note / /note show	Print the current note + git payload
/note set <text>	Replace the note body and inject
/note append <text>	Append a line and inject
/note clear	Empty the note file
/note edit	Open note in $PI_POSH_GIT_NOTE_EDITOR / $EDITOR / notepad
/note path	Show active / project / global paths
/note reload	Force re-read + inject
/note git on|off	Toggle the git block (session-local)

Note file locations (first match wins)

Priority	Path
1	$PI_POSH_GIT_NOTE_PATH
2	<cwd>/.pi/note.md (project — wins if the file exists)
3	~/.pi-posh-git/note.md (global)

/note set and /note edit write the project note by default (unless an override is set), so notes stay repo-local.

Environment variables

Variable	Default	Description
PI_POSH_GIT_NOTE_PATH	(unset)	Force a specific note file
PI_POSH_GIT_NOTE_GIT	1	Set 0 to disable the git block
PI_POSH_GIT_NOTE_TRIGGER_TURN	0	Set 1 to wake the agent when the note file changes
PI_POSH_GIT_NOTE_EDITOR	$EDITOR / $VISUAL	Editor for /note edit

Requirements

• pi coding agent
• Git installed and available in PATH
• Node.js ≥ 20

License

MIT