pi-agterm

A pi extension that integrates agent status with agterm's status indicator.

What it does

This extension reports pi agent lifecycle events to agterm so you can see at a glance whether the agent is busy, finished, or idle — directly in your terminal status bar.

Agent State	agterm Indicator	Description
active --blink	Blinking	Agent is processing a request
completed --auto-reset	Solid (auto-clears)	Agent is fully settled and waiting for input
idle	Cleared	Session started or shut down

Requirements

• pi coding agent
• agterm terminal (install guide):

  brew install --cask umputun/apps/agterm

• After installing agterm, run Help ▸ Install Agent Status Hooks… from the menu to install agterm-agent-status.sh at:

  ~/.config/agterm/agent-status/agterm-agent-status.sh
  

If the script is not found, the extension silently does nothing — it never interferes with the agent.

Installation

As a pi package

pi install git:github.com/khanton/pi-agterm
# or
pi install https://github.com/khanton/pi-agterm.git

Manual installation

Copy or symlink into pi's extensions directory:

# Global
cp -r . ~/.pi/agent/extensions/pi-agterm

# Or per-project
cp -r . .pi/extensions/pi-agterm

Quick test

pi -e ./index.ts

How it works

The extension hooks into four pi lifecycle events:

1. session_start → sets status to idle
2. agent_start → sets status to active --blink
3. agent_settled → sets status to completed --auto-reset
4. session_shutdown → sets status to idle

agent_settled is used instead of agent_end, so the indicator is not marked complete while pi is retrying, compacting, or processing queued follow-ups. Each event invokes agterm-agent-status.sh as a bounded background process. All output and errors are suppressed so the extension never disrupts the agent session.

Configuration

The script path is fixed at ~/.config/agterm/agent-status/agterm-agent-status.sh. No additional configuration is needed.

When agterm supplies AGTERM_SESSION_ID, the extension also sends a desktop notification after 10 seconds when pi has settled in a session that is not currently visible. Failed or unavailable agtermctl queries are silently ignored.

Development

npm install
npm run check
npm test

License

Private — not for distribution.