hahahhh-pi-coordinator

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pico (pi-coordinator)

> Remotely control [pi](https://github.com/xiaot623/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
- **Cron scheduling** — Create recurring tasks with auto execution or manual confirmation

## 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 |
| `/cron` | Manage scheduled tasks 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](https://go.dev/dl/) 1.25+
- [Node.js](https://nodejs.org/) 18+ (for npm scripts)
- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
- A Telegram group (forum-enabled) where the bot is a member with admin permissions

### 1. Clone & Install

```bash
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:

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

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

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

### 3. Run

```bash
# Development (uses dev_assets/)
npm run dev

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

### 4. Docker Images (for Docker runner)

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

## Configuration Reference

```yaml
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"            # host ~/.config -> container ~/.config (ro)
      - host: "~/scratch"
        mode: "rw"             # host ~/scratch -> container ~/scratch
                                  # non-~/ paths keep same-path mounts

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

```bash
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
│   └── crons/                # Cron task storage and schedule parsing
├── 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](https://github.com/xiaot623/pi-coordinator/blob/HEAD/DESIGN.md).

## License

MIT

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
Cron scheduling — Create recurring tasks with auto execution or manual confirmation

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
`/cron`	Manage scheduled tasks 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"            # host ~/.config -> container ~/.config (ro)
      - host: "~/scratch"
        mode: "rw"             # host ~/scratch -> container ~/scratch
                                  # non-~/ paths keep same-path mounts

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
│   └── crons/                # Cron task storage and schedule parsing
├── 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