Pigent

Pigent lets you run a Pi-powered assistant from Telegram.

Install it on a machine that stays online, connect a Telegram bot, then chat with your own coding/automation agent from Telegram private chats or groups. Pigent keeps per-chat sessions, supports multiple agents, and can run scheduled tasks.

What Pigent Does

• Runs as a background user service.
• Connects Telegram messages to Pi-backed agents.
• Keeps a separate session per agent + chat + thread.
• Lets you start a fresh session with /new.
• Shows current session/model/context info with /status.
• Supports model and thinking-level overrides from Telegram.
• Supports scheduled /task runs.
• Stores app state locally in SQLite.
• Persists Pi session files under ~/.pigent/pi-sessions by default.

Pigent is still an early MVP. Telegram polling is the first supported channel.

Quick Start

Install and start Pigent:

bunx @fickydev/pigent

The setup wizard will ask for:

• quick or custom setup
• Telegram bot token
• default agent routing
• optional automatic Telegram chat setup

Default app directory:

~/.pigent/app

After setup, use:

pigent status
pigent logs
pigent restart
pigent update
pigent setup

Update Pigent later:

pigent update

pigent update backs up the app, keeps your .env, SQLite database, pigent.yaml, agents/, and profiles/, refreshes package files, then restarts the service.

Create A Telegram Bot

1. Open Telegram and message @BotFather.
2. Send:

/newbot

3. Follow BotFather prompts.
4. Copy the bot token.
5. Run setup again if needed:

pigent setup

Paste the token when prompted.

You can also put it in ~/.pigent/app/.env:

TELEGRAM_BOT_TOKEN=123456:abc...

First Chat

Send your bot a message in Telegram:

/help

If automatic chat setup is enabled, Pigent will route the chat to the default assistant agent.

If automatic setup is disabled, configure the chat in pigent.yaml:

telegramChats:
  - chatId: "123456"
    title: My Private Chat
    defaultAgent: assistant
    allowedAgents:
      - assistant
    instructions: |
      Be concise.

Then restart:

pigent restart

To find a chat id, send any message to the bot and check logs:

pigent logs

Look for:

{"message":"inbound message received","chatId":"123456"}

Group chat ids often start with -100.

Telegram Commands

Common commands:

/help                         Show help
/start                        Start bot help
/agents                       List agents
/new                          Start a fresh chat session
/status                       Show session/model/context status
/model                        Pick model
/thinking                     Pick thinking level
/agent <agentId> <message>    Send message to a specific agent
@agentId <message>            Send message to a specific agent

Task commands:

/task list
/task create <intervalMs> <prompt>
/task remove <id>

Example:

/task create 3600000 Check repo status and summarize anything important.

Sessions And Memory

Pigent keeps sessions by this key:

agentId + channel + chatId + threadId

That means:

• private chats get their own session
• groups share a session by default
• Telegram forum topics can have separate sessions
• different agents do not share the same session

Use /new to end the current active session and start fresh. The next normal message creates a new Pi session file.

Use /status to inspect current state. When a Pi session exists, status shows Pi context usage; otherwise it falls back to a database estimate.

Pi session files live here by default:

~/.pigent/pi-sessions

Override with:

PIGENT_PI_SESSION_DIR=/path/to/pi-sessions

Agents

The default assistant lives at:

~/.pigent/app/agents/assistant/

Main files:

agents/assistant/agent.yaml
agents/assistant/SYSTEM.md
profiles/assistant.yaml

Example agent.yaml:

id: assistant
name: Assistant
profile: assistant
workspace: ~/.pigent/workspaces/assistant
systemPromptFile: ./SYSTEM.md
skills: []
extensions: []
permissions:
  canRunShell: false
  canEditFiles: false
  allowedPaths: []
  blockedTools: []

Edit SYSTEM.md to change how the agent behaves.

Each agent can have its own:

• name
• profile
• workspace
• system prompt
• skills/extensions
• permissions

Configuration

Important environment variables in ~/.pigent/app/.env:

DATABASE_URL=file:./pigent.db
TELEGRAM_BOT_TOKEN=
PIGENT_WORKSPACE_ROOT=~/.pigent
PIGENT_PI_SESSION_DIR=~/.pigent/pi-sessions
PIGENT_FAKE_AGENT=0
PIGENT_FALLBACK_FAKE_AGENT=1
PIGENT_AUTO_SETUP_CHATS=1
PIGENT_AUTO_SETUP_DEFAULT_AGENT=assistant

Use fake mode only for testing Telegram routing without calling Pi:

PIGENT_FAKE_AGENT=1

Running In Foreground

Run without installing a service:

bunx @fickydev/pigent run

From a checked-out repo:

bun install
bun run run

Development commands:

bun run start
bun run dev
bun run typecheck
bun run check

Data Storage

Pigent stores local runtime data in SQLite.

Default database:

~/.pigent/app/pigent.db

Configured by:

DATABASE_URL=file:./pigent.db

Important tables include:

• agents
• agent_sessions
• telegram_chats
• telegram_chat_agents
• messages
• task_configs
• task_runs
• runtime_kv

Database migrations run automatically when the daemon starts.

Architecture

High-level flow:

Telegram -> Message Router -> Agent Runner -> Pi Runner
                         \-> SQLite state

Code layout:

src/
  main.ts
  daemon/
  channels/telegram/
  agents/
  pi/
  db/
  config/
  logging/

Safety Notes

• Do not put bot tokens or API keys in prompts.
• Keep Telegram-specific logic inside the Telegram channel adapter or routing config.
• Channel adapters should not call Pi directly.
• Pi runner should not know Telegram secrets.
• Default permissions are conservative.
• File and shell capabilities should be enabled only for trusted agents/workspaces.

More Docs

• PLAN.md — architecture and milestones
• TODO.md — task checklist
• AGENTS.md — coding rules and project instructions
• CHANGELOG.md — project changes