Docs Architecture

Architecture Overview

Monorepo layout, seven packages, tool and provider registration, and how piex maps onto the Pi Extension API.

At a glance

Seven independent packages, pure Pi Extension API—tool overrides, new tools, providers, and themes without forking Pi.

Project layout

text

piex/                                  # monorepo
├── README.md                         # project entry
├── docs/                             # 📚 docs + static site (piex.dev, Pages root)
│   ├── index.html                    #   homepage
│   ├── <slug>.md                     #   doc source (Chinese only)
│   ├── notes/<slug>.md               #   blog source (Chinese only)
│   ├── {lang}/docs/<slug>/index.html #   zh/en doc HTML → /{lang}/docs/<slug>/
│   ├── {lang}/blogs/<slug>/index.html#   zh/en blog HTML → /{lang}/blogs/<slug>/
│   ├── assets/                       #   style / main / blog static assets
└── extensions/                      # pi extension packages (TS, via pi.extensions)
    ├── hashline/
    │   ├── README.md
    │   ├── package.json
    │   ├── src/                     # hashline.ts, bun-polyfill.ts, filesystem.ts, patches.ts
    │   └── test/                    # hashline.test.ts
    ├── dap/
    │   ├── README.md
    │   ├── package.json
    │   └── src/                     # dap.ts, client.ts, session.ts, config.ts, types.ts, utils.ts, defaults.json, non-interactive-env.ts
    ├── lsp/
    │   ├── README.md
    │   ├── package.json
    │   ├── src/                     # lsp.ts, defaults.json
    │   └── test/                    # lsp.test.ts, fixtures/mock-lsp-server.mjs
    ├── plan/
    │   ├── README.md
    │   ├── package.json
    │   ├── src/                     # plan.ts
    │   └── test/                    # plan.test.ts
    ├── review/
    │   ├── README.md
    │   ├── package.json
    │   └── src/                     # review.ts
    ├── xai-oauth/
    │   ├── README.md
    │   ├── package.json
    │   ├── src/                     # xai-oauth.ts, models.ts
    │   └── test/                    # xai-oauth.test.ts, models.test.ts
    ├── btw/                         # src/btw.ts
    ├── context/                     # src/context.ts
    └── ai-code-report/              # src/ai-code-report.ts (private, unpublished)
├── prompts/                          # pi prompt packages (via pi.prompts)
    └── init/
        ├── init.md                # → /init
        ├── README.md
        └── package.json             # pi.prompts: ["./init.md"]
└── themes/                          # pi theme packages (via pi.themes)
    └── dark-terminal/
        ├── theme.json               # name: "dark-terminal"
        ├── README.md
        └── package.json             # pi.themes: ["./theme.json"]

Package overview

Package	Size	Tool(s)	External deps	Origin
hashline	191 LOC + polyfill 127	overrides `edit`	`@oh-my-pi/hashline`	oh-my-pi
dap	1942 LOC + 212 JSON	`debug`	none	oh-my-pi
lsp	570 LOC + 499 JSON	`lsp`	none	oh-my-pi
plan	348 LOC	`/plan`, `/todos`	none	Pi example
review	330 LOC	`/review`, `review`	none	oh-my-pi
init	prompt only	`/init`	none	OpenCode
xai-oauth	530 LOC + 419 models	`/login` xAI Grok OAuth (live model discovery)	none	oh-my-pi / pi-grok
theme-dark-terminal	—	dark high-contrast terminal theme	none	opencode-themes

Tool registration

Tool	Source	Mode	Notes
`read`	Pi built-in	read	Read files
`bash`	Pi built-in	r/w	Run commands
`write`	Pi built-in	write	Write files
`grep`	Pi built-in	read	Search content
`find`	Pi built-in	read	Search files
`ls`	Pi built-in	read	List directories
`edit`	hashline	write	hashline edit (overrides built-in)
`debug`	dap	r/w	DAP debug (launch/attach/step/evaluate)
`lsp`	lsp	r/w	LSP (diagnostics/nav/rename；edit 后 ERROR)
`review`	review	read	Code review (diff/file/branch/commit)

Provider registration

Provider	Source	Auth	Notes
`xai-oauth`	xai-oauth	OAuth subscription	SuperGrok / X Premium+ login; subscription models via cli-chat-proxy; background model discovery after login

Pi Extension API mapping

Concept	Origin	piex impl	Pi API
Override edit tool	omp	hashline.ts	`pi.registerTool({ name: "edit" })`
Hook read, append header	omp	hashline.ts	`pi.on("tool_result", ...)`
Register debug tool	omp	dap.ts	`pi.registerTool({ name: "debug" })`
Cleanup DAP processes	omp	dap.ts	`pi.on("session_shutdown", ...)`
Register lsp tool	omp	lsp.ts	`pi.registerTool({ name: "lsp" })`
Post-edit diagnostics hook	OpenCode	lsp.ts	`pi.on("tool_result")` on edit/write
Plan mode /plan	Pi example	plan.ts	`pi.registerCommand("plan", ...)`
Read-only tool set	Pi example	plan.ts	`pi.setActiveTools([...])`
Block dangerous cmds	Pi example	plan.ts	`pi.on("tool_call", ...)` → block
Progress [DONE:n]	Pi example	plan.ts	`pi.on("turn_end", ...)`
Interactive review menu	omp	review.ts	`pi.registerCommand("review", ...)`
Register review tool	omp	review.ts	`pi.registerTool({ name: "review" })`
Guided AGENTS.md setup	OpenCode	init `prompts/init/init.md`	`pi.prompts` → `/init`
Persist state	Pi	plan.ts	`pi.appendEntry("plan-mode", ...)`
Footer / Widget	Pi	plan.ts	`ctx.ui.setStatus/setWidget(...)`
Register xAI OAuth provider	omp	xai-oauth.ts	`pi.registerProvider("xai-oauth", { oauth: {...} })`

Source Markdown: docs/architecture.md