pico (pi-coordinator)

Remotely control pi via Telegram. Start AI coding tasks in private chat, and watch the full execution progress unfold in a group chat Forum Topic.

How It Works

Private Chat                pico (Coordinator)           pi (AI Agent)
────────────                ────────────────           ─────────────
  /new "fix bug"  ──────▶  Select workspace     ──────▶  Spawn pi process
                            Create Forum Topic           Execute task
                            Send prompt via stdin        Stream progress
                                                               │
  Group Topic ◀──────────────────────────────────────────────┘
  (real-time progress via pi-trace extension)

You send commands and task descriptions to the bot in a private chat.
The bot spawns a pi agent process inside a Forum Topic in a configured Telegram group, where you can follow every step — thinking, tool calls, assistant messages, and summary — in real-time.

Features

• Remote task execution — Start, steer, and resume AI coding sessions from Telegram
• Real-time progress tracking — Thinking, tool calls, and outputs streamed to a group topic
• Workspace & session management — Browse, sync, and organize historical sessions
• Multi-mode runners — Local (direct), Worktree (git-isolated), Docker (fully sandboxed)
• Per-session model selection — Choose AI models at Global / Workspace / Session scope
• Git integration — Rebase, commit, and view HTML diffs directly from Telegram
• Todo management — Save and organize task ideas across workspaces

Commands

Command	Description
/help	Show available commands
/workspace	Browse workspaces and select a session
/add	Add a workspace from your filesystem
/new [description]	Start a new task in a workspace
/todo	Manage saved todos across workspaces
/status	List all active sessions with details
/detail	Show workspace path, run mode, model, and git summary
/stop	Force-stop the current session
/open	Open the workspace in your terminal (iTerm2 / xdg-open)
/rebase	Rebase a worktree/docker session from the main branch
/commit <message>	Commit worktree/docker session changes back to the main branch
/diff [args]	Generate an HTML diff of current changes
/sync	Import historical sessions from disk into the database
/pin [query]	Pin a workspace; subsequent messages auto-start new tasks
/unpin	Clear the pinned workspace
/model	Configure model at Global / Workspace / Session level
/bots	Show managed Telegram bot accounts

Session Topic Commands

Inside a session Forum Topic, you can send follow-up messages at any time — the bot forwards them to the running (or restarted) pi process to continue the task. The following commands also work inside a topic:

Command	Context
/stop	Force-stop the current topic's session
/open	Open the session's workspace locally
/rebase	Rebase the session's worktree (worktree/docker modes)
/commit <msg>	Commit and push changes (worktree/docker modes)
/diff [args]	Generate a syntax-highlighted HTML diff

Run Modes

When starting a new task, you can choose one of three execution modes:

Mode	Working Directory	Isolation
Local	Original workspace	None — edits files directly
Worktree	Per-session Git worktree	File changes isolated on a separate branch
Docker	Per-session Git worktree in a container	Full filesystem + environment sandbox

Worktree and Docker modes require the workspace to be a Git repository.

Quick Start

Prerequisites

• Go 1.25+
• Node.js 18+ (for npm scripts)
• A Telegram bot token (from @BotFather)
• A Telegram group (forum-enabled) where the bot is a member with admin permissions

1. Clone & Install

git clone https://github.com/xiaot623/pi-coordinator.git
cd pi-coordinator
npm install

2. Configuration

On first run, a config template is created. Fill in the required values:

npm run dev
# → creates dev_assets/pico.config.yaml

Edit dev_assets/pico.config.yaml (or ~/.mypi/pico/config.yaml for production):

telegram:
  bot_token: "123456:ABC-DEF1234"
  group_chat_id: -1001234567890
  allowed_users:
    - 123456789

3. Run

# Development (uses dev_assets/)
npm run dev

# Production build
go build -o pico ./cmd/pico
./pico

4. Docker Images (for Docker runner)

docker build -f docker/Dockerfile --target pi-agent -t pi-agent:latest .

Configuration Reference

telegram:
  bot_token: ""                # Telegram bot token
  group_chat_id: 0             # Forum group chat ID
  allowed_users: []            # Telegram user IDs allowed to use the bot

plugins:
  - "@hahahhh/pi-trace@next"   # pi extensions (pi-trace is required for progress)

plugin_update_interval_minutes: 1440

runner:
  local:
    idle_timeout: 5m
    session_dir: "~/.pi/agent/sessions"
  worktree:
    idle_timeout: 5m
    session_dir: ""
  docker:
    idle_timeout: 5m
    image: "pi-agent:latest"
    network: "bridge"
    agent_dir: "~/.pi/agent"
    skills_dir: "~/.agents/skills"
    agent_mount_mode: "rw"
    extra_mounts:
      - "~/.config"            # same-path read-only mount
      - host: "~/scratch"
        mode: "rw"             # optional: ro | rw

open_tool: "iterm2"            # macOS: iterm2 / terminal; Linux: xdg-open
global_model: ""               # Global default model (empty = pi default)

diff:
  delivery: send               # send (to Telegram) | open (in browser) | all

Environment Variables

Variable	Description	Default
PICO_ENV	Set to dev to use ./dev_assets/ for config and database	(production)

npm Scripts

npm run dev           # Run in development mode
npm test              # Run tests
npm run build         # Build native binary via scripts/build-native.js
npm run check         # Lint (go vet ./...)
npm run release:patch # Bump patch version, tag, and push
npm run release:minor # Bump minor version, tag, and push
npm run release:major # Bump major version, tag, and push

Project Structure

pico/
├── cmd/pico/main.go          # Entry point
├── internal/
│   ├── app/                  # Application orchestration
│   ├── config/               # YAML config loading and hot-reloading
│   ├── diff/                 # HTML diff rendering
│   ├── gitops/               # Shell script wrappers for git operations
│   ├── runner/               # Local / Worktree / Docker pi process management
│   ├── session/              # Session scanner (sync from disk)
│   ├── source/telegram/      # Telegram bot: handlers, keyboard UI, routing
│   ├── store/                # SQLite persistence
│   └── todos/                # Todo list storage
├── docker/                   # Docker image definitions
├── scripts/                  # Build and release scripts
├── docs/                     # Additional documentation
├── DESIGN.md                 # Architecture and design document
└── package.json              # npm package metadata

Architecture

For a detailed architecture overview, design decisions, and internal data models, see DESIGN.md.

License

MIT