@gavin-hu/my-pi-agent

Personal Pi customizations, packaged as a Pi package: worktree isolation and rewind snapshots, question, todo, goal, plan, subagent, job, watch, web-access, file-browse, file-open, document, memory, wechat, and bytefly.

Packages

Package details

extensiontheme

Install @gavin-hu/my-pi-agent from npm and Pi will load the resources declared by the package manifest.

npm repo home report

$ pi install npm:@gavin-hu/my-pi-agent

Package: @gavin-hu/my-pi-agent
Version: 0.11.4
Published: Oct 18, 2026
Downloads: 204/mo · 204/wk
Author: gavin-hu
License: MIT
Types: extension, theme
Size: 6.3 MB
Dependencies: 8 dependencies · 5 peers

Pi manifest JSON

{
  "image": "https://raw.githubusercontent.com/gavin-hu/my-pi-agent/main/assets/chrome.png",
  "themes": [
    "./themes/*.json"
  ],
  "extensions": [
    "./extensions/worktree/index.ts",
    "./extensions/rewind/index.ts",
    "./extensions/question/index.ts",
    "./extensions/todo/index.ts",
    "./extensions/goal/index.ts",
    "./extensions/plan/index.ts",
    "./extensions/subagent/index.ts",
    "./extensions/job/index.ts",
    "./extensions/watch/index.ts",
    "./extensions/web-access/index.ts",
    "./extensions/file-browse/index.ts",
    "./extensions/document/index.ts",
    "./extensions/file-open/index.ts",
    "./extensions/memory/index.ts",
    "./extensions/wechat/index.ts",
    "./extensions/bytefly/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

my-pi-agent

English · 简体中文

Plan before you act, delegate the work, keep the main checkout clean, and carry context across sessions. my-pi-agent is a single Pi package that adds sixteen extensions and two themes — install the pack, turn off what you do not want, and keep using Pi unchanged.

A terminal window running the Pi TUI with the bytefly header, hint row, context and loaded extensions, a turn separator, and the status bar

Why this pack
Quick start
What you get
Configuration
Documentation
Requirements
Contributing
License

Why this pack

Pi ships a small, sharp core. This package is the layer on top for people who want the agent to think first and work safely:

Plan, then execute. A read-only planning mode turns a task into a reviewed plan file that the agent then follows step by step.
Delegate and parallelize. Run specialist subagents in their own Pi processes to explore, review, test, or implement while you keep the thread.
Never wreck the checkout. Work happens in an isolated git worktree, and every prompt is snapshotted so a bad turn is one /rewind away.
Remember across sessions. Durable notes live in plain markdown that you can read, edit, and version.
Reach the web and your files. Search, fetch, browse, open, and read documents — all from inside the session.

Everything is optional and independently toggleable. Nothing is patched or forked: Pi discovers the resources through the pi manifest in package.json, so the package upgrades with Pi like any other.

Quick start

Requires a working Pi installation.

pi install npm:@gavin-hu/my-pi-agent                       # install from npm
pi install git:github.com/gavin-hu/my-pi-agent             # install from git
pi install git:github.com/gavin-hu/my-pi-agent@v0.8.0      # pin a release
pi install ./ -l                                           # project-local (.pi/settings.json)
pi -e .                                                    # try it for one run

Then, from inside Pi:

/bytefly [extension] [refresh] opens the control center on Extensions, lists every loaded extension with its runtime health, and enables or disables one.
/bytefly settings opens the control center's Settings section: bytefly startup TUI, desktop notifications, the transcript rail glyph, output padding, and the hardware cursor, with Space/Enter to change a value and Tab for Global/Project scope.
/bytefly doctor [extension] [refresh] prints the doctor report — run_doctor's text — and checks that each enabled extension has what it needs at runtime.
/settings → Theme selects a theme.
/plan <task> starts a task in read-only planning mode.

What you get

Sixteen extensions and two themes, grouped by what you are trying to do. Each extension's own README.md has the full tool and command surface.

Plan and delegate

Extension	Tools and commands	What it does
`plan`	`enter_plan_mode`, `write_plan`, `exit_plan_mode`, `set_plan_steps`, `/plan`, `--plan`	Read-only planning: the model investigates, saves a plan under `.pi/plans`, and you approve it before anything is written. Review in the TUI, or open it in a browser to leave inline comments.
`subagent`	`subagent`	Delegate a task to a specialist agent (`explorer`, `planner`, `reviewer`, `worker`, `researcher`, `tester`, `debugger`, `documenter`) in its own Pi process — single, parallel, or chained.
`todo`	`todo`, `/todos`	A persistent task list (`pending` / `in_progress` / `completed`) with a one-line widget.
`goal`	`goal`, `/goal`	A persistent session objective, kept in a widget and restated before each turn.
`question`	`ask_user_question`	Ask you one or more structured questions (labelled options plus free-form "Other") and wait.
`job`	`job`, `/jobs`	Run long-lived shell commands in the background; inspect logs, wait, or kill them.
`watch`	`watch`, `/watch`	Tail a file or command output, match lines against patterns, and alert you or hand matching lines to the agent.

Keep your work safe

Extension	Tools and commands	What it does
`worktree`	`enter_worktree`, `exit_worktree`, `prune_worktrees`, `list_worktrees`, `/worktree*`, `--worktree`	Work inside an isolated `git worktree` on its own branch; the built-in read/write/edit/bash tools follow, and cleanup refuses to throw work away.
`rewind`	`/rewind`, `↺ N` status chip	Snapshot the repo on every prompt under `refs/pi/rewind` and restore code, conversation, or both.
`memory`	`memory`, `/memory`	Durable cross-session notes as human-editable markdown, injected into each run and managed through the `/memory` picker.

Reach the world

Extension	Tools and commands	What it does
`web-access`	`web_search`, `web_fetch`	Search the web (keyless DuckDuckGo by default, optional SearXNG or Brave) and fetch a page as readable text, with paging, `find`, per-hop SSRF checks, and optional PDF support.
`file-browse`	`/browse`	Start a loopback, read-only file browser rooted at the working directory, with Markdown preview and a fuzzy quick-open palette.
`document`	`read_doc`	Extract text from a local PDF, DOCX, DOC, ODT, RTF, or XLSX in process, paged.
`file-open`	`/open`, `open_path`	Open or reveal a file or directory in the OS-native application.
`wechat`	`/wechat`, `send_wechat`	Bridge a WeChat chat to the live session over the Weixin iLink bot API; inbound text, images, and files become turns.

Chrome and upkeep

Extension	Tools and commands	What it does
`bytefly`	`/bytefly` (with the `doctor` and `settings` subcommands), `run_doctor`	A themed header and width-adaptive footer, a two-row `You` nameplate on each user message, a rule between completed turns, a shared transcript notice, a tool block that leads with its call line and rails its result body two columns under it (the rail glyph is the `chrome.rail` setting), a live elapsed counter on Pi's working row, the `/bytefly` control center — an Extensions section that lists every extension with its health and enables or disables one, plus a Settings section with five curated preferences (`/bytefly settings`) — `/bytefly doctor` prints the doctor report, and an opt-in `notify` capability that raises OS notifications when a run or a background job finishes or the agent asks for input. DeepSeek is priced out of the box, and `bytefly.json` is the shared config document every extension reads.
`bytefly-dark` / `bytefly-light`	`/settings` → Theme	A GitHub-inspired dark palette and its light companion, with optional automatic light/dark switching.

Screens

Tool renderings

Every tool block as the transcript draws it — the tool's own call line as the headline, then the result body two columns under it behind the transcript rail — each tool's own renderer (or bytefly's generic fallback): the user nameplate and a notice, Pi's built-ins, and every tool this package registers. The rail glyph is the chrome.rail setting.

A full-page reference of every tool block: the user nameplate, a notice, the turn rule, Pi's read, write, edit, bash, grep, find, and ls renderers, and every package tool — todo, goal, memory, job, watch, subagent, web_search, web_fetch, read_doc, open_path, run_doctor, send_wechat, ask_user_question, the plan tools, and the worktree tools

bun run screenshot:tools regenerates it; bun run screenshot:tool-pngs writes one image per tool under assets/tools/.

Configuration

Most extensions need no configuration. Every setting lives in one shared document, bytefly.json, read from <agent-dir>/bytefly.json and merged with <cwd>/.pi/bytefly.json (project wins), under a top-level section named for the extension. Each extension's README.md lists its keys, docs/configuration.md indexes them, and assets/bytefly.schema.json validates the file.

Every extension is on by default. To load the pack without some of them, set PI_DISABLED_EXTENSIONS to a comma- or whitespace-separated list of extension names (the directory names under extensions/):

PI_DISABLED_EXTENSIONS=todo,job pi -e .

Names are compared case-insensitively and unknown names are ignored. This only stops the factories from registering; to drop the whole package, use Pi's --no-extensions or remove the package from your settings.

Documentation

Guide	What it covers
Getting started	Requirements, install options, verifying the load, themes.
Extensions	The full catalog of every extension and theme.
Configuration	Config-file resolution, the per-extension index, environment variables.
Architecture	How the package, its extensions, and `lib/` fit together.
Development	Local setup, checks, tests, cross-platform notes, and the release process.
Security	Trust boundaries for the loopback and remote surfaces.

Requirements

Pi — a working installation; my-pi-agent is a package, not a fork.
OS — Windows, macOS, and Linux; the full check suite runs on all three in CI.
git on PATH for the worktree and rewind extensions; everything else degrades or disables cleanly, and /bytefly doctor tells you what is missing.
Optional runtime pieces (for example a browser for HTML exports) are reported per extension by /bytefly doctor.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md for the setup, the worktree branch flow, and the checks a change must pass. AI coding agents should read AGENTS.md.

License

MIT