pi-inject

CLI tool and pi extension for injecting messages into a running pi TUI via Unix Domain Socket.

Overview

This tool enables external scripts, hotkeys, or applications to communicate with a running pi TUI session. Useful for:

• Triggering pi actions from external scripts
• Hotkey integration (e.g., send selected text to pi)
• CI/CD pipeline integration
• Custom automation workflows

Installation

Option 1: Development (Local)

# Clone or copy to your extensions directory
cp -r pi-inject ~/.pi/agent/extensions/

# Make the CLI executable
chmod +x ~/.pi/agent/extensions/pi-inject/src/pi-inject.ts

Option 2: npm Package

npm install -g pi-inject

Configuration

Socket Path

By default, the socket is created at ~/.pi/injector.sock. Override with the PI_INJECTOR_SOCKET environment variable:

# Custom socket path
PI_INJECTOR_SOCKET=/tmp/pi-inject.sock pi

# Then use the same path in CLI
PI_INJECTOR_SOCKET=/tmp/pi-inject.sock pi-inject "message"

Important: Both pi (with the extension) and the CLI must use the same socket path.

Usage

Starting pi with the Extension

The extension auto-starts when pi loads it. Ensure it's in your extensions directory:

pi

Or load explicitly:

pi -e ./pi-inject

CLI Commands

# Send a message (steer by default)
pi-inject "Fix the tests"

# Send a steer message (interrupts current processing)
pi-inject --steer "Stop that and focus on X"

# Queue a follow-up (waits for current task)
pi-inject --followup "After this, also do Y"

# Execute a slash command
pi-inject /reload
pi-inject /compact
pi-inject /model

# Check if injector is running
pi-inject --ping

# With verbose output
pi-inject -v "Your message"

In-pi Commands

When pi is running with the extension:

/inject-status   # Check socket status
/inject-restart # Restart the socket server

Protocol

The socket server listens on ~/.pi/injector.sock and accepts JSON messages:

{ "type": "steer", "message": "Focus on X" }
{ "type": "followup", "message": "After this, do Y" }
{ "type": "command", "command": "/reload" }
{ "type": "ping" }

Responses:

{ "type": "ok" }
{ "type": "error", "message": "Command not found" }
{ "type": "pong" }

Architecture

┌─────────────────┐         ┌─────────────────┐
│   pi-inject     │ ──JSON──│  pi-injector    │
│   CLI client    │  socket │  (extension)    │
└─────────────────┘         └────────┬────────┘
                                     │
                              ┌──────▼──────┐
                              │  pi TUI      │
                              │  (running)   │
                              └──────────────┘

Requirements

• pi coding agent
• Node.js 18+

License

MIT