pi-afk

afk

A Pi package extension that allows the agent to communicate with the user when they're afk.

Status

AFK provides a Pi extension MVP with /afk, /afk-settings, and an afk agent tool backed by a linked Telegram bot.

AFK MVP usage

• Create a Telegram bot with BotFather and copy the bot token.
• Start Pi with this package loaded: pi -e ..
• Run /afk-settings.
• Paste the bot token when prompted.
• Send the displayed one-time code directly to the Telegram bot.
• Run /afk to enable AFK mode for the current Pi session.
• While AFK mode is on, the agent can use the afk tool to notify you or ask questions through Telegram.
• Run /afk again to turn AFK mode off.

AFK mode is session-scoped. It turns off on /new, /resume, /fork, /clone, /reload, and Pi shutdown. Telegram bot settings remain saved in user config.

Install for local development

npm install
npm run check

Use with Pi during development

pi -e .

Pi loads the package through package.json:

{ "pi": { "extensions": ["./extensions/index.ts"] } }

Project layout

extensions/index.ts             Pi extension entry point
extensions/controller.ts        AFK runtime orchestration
extensions/config.ts            Telegram config persistence
extensions/lock.ts              Bot-token process lock
extensions/ask-queue.ts         Serialized blocking question queue
extensions/telegram.ts          grammY bridge
extensions/telegram-format.ts   Telegram question/button formatting
extensions/types.ts             Shared schemas and types
extensions/README.md            Extension-specific notes
tests/                          Node test runner tests

Release checks

npm run check