pi-agent-extensions-extra

Extra extensions for pi coding agent — useful for some, not all

---

🌅 Overview

pi-agent-extensions-extra is a collection of extra pi coding agent extensions — useful for some, not all. Each extension is a standalone TypeScript module that plugs into pi’s extension system.

This is a companion to pi-agent-extensions, which contains extensions intended for broader use. The extensions here are more opinionated or depend on external services (e.g. Telegram).

📦 Installation

Choose one of the following methods:

Method 1: Install via pi Package Manager

pi install git:github/rytswd/pi-agent-extensions-extra

This command:

1. Clones the repository to ~/.pi/agent/git/
2. Runs npm install to install dependencies
3. Adds the package path to ~/.pi/agent/settings.json ("packages" stanza)
4. Makes all extensions available to pi automatically

Method 2: Manual Installation via Git Clone

1. Clone the repository to any directory:

git clone https://github.com/rytswd/pi-agent-extensions-extra.git ~/path/to/pi-agent-extensions-extra

1. Add the package to pi’s configuration by editing ~/.pi/agent/settings.json:

{
  "packages": [
    "/absolute/path/to/pi-agent-extensions-extra"
  ]
}

Method 3: Copy Individual Extensions

For selective installation, copy specific extension directories to ~/.pi/agent/extensions/:

# Copy only the extensions you want
cp -r /path/to/pi-agent-extensions-extra/telegram-connect ~/.pi/agent/extensions/

Extensions are auto-discovered from ~/.pi/agent/extensions/ — pi loads all *.ts files and index.ts files in subdirectories.

Note: The bridge/ directory is a Go binary, not a pi extension. Build it separately:

cd /path/to/pi-agent-extensions-extra/bridge
CGO_ENABLED=0 go install .

✨ Extensions

telegram-connect - Bridge pi sessions to Telegram

• Source: telegram-connect/
• License: MIT
• Command: /telegram
• Config: ~/.config/pi-agent-extensions/telegram-connect/config.json
• Based on: walkie by aldoborrero

Description: Bridges pi coding agent sessions to Telegram for mobile use. Fully bidirectional — agent responses are pushed to Telegram, and text/photos from Telegram are injected as user prompts.

Features:

• Bidirectional messaging: pi → Telegram responses with stats; Telegram → pi prompt injection
• Live draft streaming: See the agent’s response as it’s generated via sendMessageDraft (512B/4s/12s throttle)
• Phase-aware heartbeat: 🧠 Thinking… / 🔧 tool… status updates while the agent works
• Inline keyboards: The agent can present tappable choice buttons
• Forum topics: Scope each project to its own Telegram topic thread
• Message queue: Messages arriving mid-run are queued and drained after each agent turn
• Text debounce: Rapid consecutive messages are merged into one prompt (3s window)

Setup (private chat):

1. Talk to @BotFather and create a new bot. Copy the bot token.
2. In pi, run /telegram setup and enter the token.
3. Send any message to your bot in Telegram to pair.

Setup (group with topics):

Use a group when you want per-project topic threads (each pi project gets its own topic in the group).

1. Create a Telegram group and enable Topics in the group settings (this auto-converts to a supergroup).
2. Add your bot to the group and make it an admin.
3. In pi, run /telegram setup and enter the bot token.
4. Send a message in the group (not in private chat) to pair — the extension picks up the group’s chat ID.
5. Optionally run /telegram topic to create a dedicated topic thread for this project.

The session is connected immediately after pairing. Future pi sessions need /telegram or /telegram start to reconnect (credentials are remembered).

Pi commands:

Command	Description
/telegram	Toggle on/off
/telegram setup	Enter pairing mode (interactive)
/telegram start	Enable and start polling
/telegram stop	Disable and stop polling
/telegram stream	Toggle live draft streaming
/telegram status	Show current config
/telegram topic	Create a forum topic and bind this instance

Telegram commands (from your phone):

Command	Description
/abort	Stop the current agent run
/status	Show agent state, model, context usage
/compact	Compress context to free up space
/new	Queue a new session request
/think	Cycle thinking level: none → low → high
/stream	Toggle live draft preview
/mute	Silence notifications (polling continues)
/unmute	Resume notifications

Environment variables:

Variable	Description
PI_NO_TELEGRAM=1	Disable the extension entirely at startup

Bridge mode (multi-session):

When you configure a topic (via /telegram topic or /telegram setup), the extension uses pi-bridge — a lightweight Go server that handles all Telegram API polling centrally. Multiple pi sessions connect to the bridge via localhost, each routed by topic ID. No more message races between sessions.

The bridge is spawned automatically on first /telegram if the pi-bridge binary is in your PATH. Build it once:

cd bridge
CGO_ENABLED=0 go install .
# Binary: $GOBIN/pi-bridge (typically ~/go/bin/pi-bridge)

Requires Go 1.23+. The binary is a single static executable with zero external dependencies.

Alternatively, set PI_BRIDGE_BIN to point to the binary:

export PI_BRIDGE_BIN=/path/to/pi-bridge

Sessions without a topic fall back to direct Telegram polling (single-session only).

Differences from walkie:

• No voice/STT support (removed entirely)
• XDG-compliant config at ~/.config/pi-agent-extensions/telegram-connect/ (Nix-store safe)
• Standalone — no dependency on pi-agent-kit internals
• Multi-session safe via pi-bridge (Go server with adapter pattern)
• Command: /telegram instead of /walkie

⚙️ Configuration

Once installed, pi can use all of the extensions listed in this package’s package.json. By default, all extensions are enabled.

To manage which extensions are active, run:

pi config

Changes are saved to ~/.pi/agent/settings.json and take effect on the next pi session.

🚀 Quick Start

After installation, start using pi normally:

pi

Try the Extensions

• telegram-connect: Run /telegram setup to pair with your Telegram bot

📁 Structure

pi-agent-extensions-extra/
├── telegram-connect/       # Telegram extension (TypeScript)
├── bridge/                 # Message bridge server (Go)
├── package.json
└── README.org

🔧 Adding New Extensions

To add a new extension, create a directory with an index.ts file.

A minimal extension looks like:

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  pi.on("session_start", async (_event, ctx) => {
    ctx.ui.notify("My extension loaded!", "info");
  });
}

See the pi documentation for the full extension API.

🙏 Acknowledgements

• Mario Zechner: pi coding agent
• aldoborrero: pi-agent-kit — telegram-connect is based on the walkie extension

📄 License

MIT