From 94952bd6c05bce0e4753ee9800092e08d93e49ff Mon Sep 17 00:00:00 2001 From: Mario Zechner Date: Sun, 25 Jan 2026 20:33:19 +0100 Subject: [PATCH] docs(coding-agent): update README intro, add packages/prompt-templates/themes docs - Rewrote README intro to emphasize extensibility and pi packages - Added Pi Packages section to README - Created docs/packages.md covering install, sources, manifest, filtering - Created docs/prompt-templates.md covering format and arguments - Created docs/themes.md with overview linking to theme.md --- packages/coding-agent/README.md | 13 +- packages/coding-agent/docs/packages.md | 158 ++++++++++++++++++ .../coding-agent/docs/prompt-templates.md | 57 +++++++ packages/coding-agent/docs/themes.md | 46 +++++ 4 files changed, 272 insertions(+), 2 deletions(-) create mode 100644 packages/coding-agent/docs/packages.md create mode 100644 packages/coding-agent/docs/prompt-templates.md create mode 100644 packages/coding-agent/docs/themes.md diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md index 999cd697..1a806310 100644 --- a/packages/coding-agent/README.md +++ b/packages/coding-agent/README.md @@ -9,9 +9,11 @@ Build status

-A terminal-based coding agent with multi-model support, mid-session model switching, and a simple CLI for headless coding tasks. +Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git. -Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows-setup)). [Separately maintained port](https://github.com/VaclavSynacek/pi-coding-agent-termux) works on Termux/Android. +Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow. + +Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. See [clawdbot/clawdbot](https://github.com/clawdbot/clawdbot) for a real-world SDK integration. ## Table of Contents @@ -42,6 +44,7 @@ Works on Linux, macOS, and Windows (requires bash; see [Windows Setup](#windows- - [Prompt Templates](#prompt-templates) - [Skills](#skills) - [Extensions](#extensions) + - [Pi Packages](#pi-packages) - [CLI Reference](#cli-reference) - [Tools](#tools) - [Programmatic Usage](#programmatic-usage) @@ -1283,6 +1286,12 @@ await ctx.ui.custom((tui, theme, done) => ({ > See [docs/tui.md](docs/tui.md) for TUI components and custom rendering. > See [examples/extensions/](examples/extensions/) for working examples. +### Pi Packages + +Pi packages bundle extensions, skills, prompt templates, and themes for sharing through npm or git. A package can declare resources in `package.json` under the `pi` key, or use the conventional `extensions/`, `skills/`, `prompts/`, and `themes/` directories. Install packages with `pi install` and manage them in the `packages` settings array. + +See [docs/packages.md](docs/packages.md) for package structure, filtering, and install behavior. + --- ## CLI Reference diff --git a/packages/coding-agent/docs/packages.md b/packages/coding-agent/docs/packages.md new file mode 100644 index 00000000..ad6e7f71 --- /dev/null +++ b/packages/coding-agent/docs/packages.md @@ -0,0 +1,158 @@ +> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes. + +# Pi Packages + +Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories. + +## Table of Contents + +- [Install and Manage](#install-and-manage) +- [Package Sources](#package-sources) +- [Creating a Pi Package](#creating-a-pi-package) +- [Package Structure](#package-structure) +- [Package Filtering](#package-filtering) +- [Enable and Disable Resources](#enable-and-disable-resources) +- [Scope and Deduplication](#scope-and-deduplication) + +## Install and Manage + +```bash +pi install npm:@foo/bar@1.0.0 +pi install git:github.com/user/repo@v1 +pi install https://github.com/user/repo # raw URLs work too + +pi remove npm:@foo/bar +pi list # show installed packages from settings +pi update # update all non-pinned packages +``` + +By default, `install` and `remove` write to global settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup. + +To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only: + +```bash +pi -e npm:@foo/bar +pi -e git:github.com/user/repo +``` + +## Package Sources + +Pi accepts three source types in settings and `pi install`. + +### npm + +``` +npm:@scope/pkg@1.2.3 +npm:pkg +``` + +- Versioned specs are pinned and skipped by `pi update`. +- Global installs use `npm install -g`. +- Project installs go under `.pi/npm/`. + +### git + +``` +git:github.com/user/repo@v1 +https://github.com/user/repo@v1 +``` + +- Raw `https://` URLs work without the `git:` prefix. +- Refs pin the package and skip `pi update`. +- Cloned to `~/.pi/agent/git//` (global) or `.pi/git//` (project). +- Runs `npm install` after clone or pull if `package.json` exists. + +### Local Paths + +``` +/absolute/path/to/package +./relative/path/to/package +``` + +Local paths work in settings but not with `pi install`. If the path is a file, it loads as a single extension. If it is a directory, pi loads resources using package rules. + +## Creating a Pi Package + +Add a `pi` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability. + +```json +{ + "name": "my-package", + "keywords": ["pi-package"], + "pi": { + "extensions": ["./extensions"], + "skills": ["./skills"], + "prompts": ["./prompts"], + "themes": ["./themes"] + } +} +``` + +Paths are relative to the package root. Arrays support glob patterns and `!exclusions`. + +## Package Structure + +### Convention Directories + +If no `pi` manifest is present, pi auto-discovers resources from these directories: + +- `extensions/` loads `.ts` and `.js` files +- `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills +- `prompts/` loads `.md` files +- `themes/` loads `.json` files + +### Bundling Other Pi Packages + +Bundle other pi packages by adding them as dependencies and listing them in `bundledDependencies`. Reference their resources via `node_modules/` paths. + +```json +{ + "dependencies": { + "shitty-extensions": "^1.0.1" + }, + "bundledDependencies": ["shitty-extensions"], + "pi": { + "extensions": ["extensions", "node_modules/shitty-extensions/extensions"], + "skills": ["skills", "node_modules/shitty-extensions/skills"] + } +} +``` + +`bundledDependencies` embeds the package in the published tarball, keeping paths stable. See `pi-package-test` for a working example. + +## Package Filtering + +Filter what a package loads using the object form in settings: + +```json +{ + "packages": [ + "npm:simple-pkg", + { + "source": "npm:my-package", + "extensions": ["extensions/*.ts", "!extensions/legacy.ts"], + "skills": [], + "prompts": ["prompts/review.md"], + "themes": ["+themes/legacy.json"] + } + ] +} +``` + +- Omit a key to load all of that type. +- Use `[]` to load none of that type. +- `!pattern` excludes matches. +- `+pattern` force-includes, even if excluded by manifest. +- Filters layer on top of the manifest. They narrow down what is already allowed. + +## Enable and Disable Resources + +Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. Works for both global (`~/.pi/agent`) and project (`.pi/`) scopes. + +## Scope and Deduplication + +Packages can appear in both global and project settings. If the same package appears in both, the project entry wins. Identity is determined by: + +- npm: package name +- git: repository URL without ref +- local: resolved absolute path diff --git a/packages/coding-agent/docs/prompt-templates.md b/packages/coding-agent/docs/prompt-templates.md new file mode 100644 index 00000000..e1b65819 --- /dev/null +++ b/packages/coding-agent/docs/prompt-templates.md @@ -0,0 +1,57 @@ +> pi can create prompt templates. Ask it to build one for your workflow. + +# Prompt Templates + +Prompt templates are Markdown snippets that expand into full prompts when you type `/name` in the editor. + +## Locations + +Pi loads prompt templates from: + +- Global: `~/.pi/agent/prompts/*.md` +- Project: `.pi/prompts/*.md` +- Packages: `prompts/` directories or `pi.prompts` entries in `package.json` +- Settings: `prompts` array with files or directories +- CLI: `--prompt-template ` (repeatable) + +Disable discovery with `--no-prompt-templates`. + +## Format + +```markdown +--- +description: Review staged git changes +--- +Review the staged changes (`git diff --cached`). Focus on: +- Bugs and logic errors +- Security issues +- Error handling gaps +``` + +- The filename becomes the command name. `review.md` becomes `/review`. +- `description` is optional. If missing, the first non-empty line is used. + +## Arguments + +Templates support positional arguments and simple slicing: + +- `$1`, `$2`, ... positional args +- `$@` or `$ARGUMENTS` for all args joined +- `${@:N}` for args from the Nth position (1-indexed) +- `${@:N:L}` for `L` args starting at N + +Example: + +```markdown +--- +description: Create a component +--- +Create a React component named $1 with features: $@ +``` + +Usage: `/component Button "onClick handler" "disabled support"` + +## Loading Rules + +- Template discovery in `prompts/` is non-recursive. +- If you want templates in subdirectories, add them explicitly via `prompts` settings or a package manifest. diff --git a/packages/coding-agent/docs/themes.md b/packages/coding-agent/docs/themes.md new file mode 100644 index 00000000..6c223a25 --- /dev/null +++ b/packages/coding-agent/docs/themes.md @@ -0,0 +1,46 @@ +> pi can create themes. Ask it to build one for your setup. + +# Themes + +Themes are JSON files that define colors for the TUI. You can select themes in `/settings` or via `settings.json`. + +## Locations + +Pi loads themes from: + +- Built-in: `dark`, `light` +- Global: `~/.pi/agent/themes/*.json` +- Project: `.pi/themes/*.json` +- Packages: `themes/` directories or `pi.themes` entries in `package.json` +- Settings: `themes` array with files or directories +- CLI: `--theme ` (repeatable) + +Disable discovery with `--no-themes`. + +## Format + +Themes use this structure: + +```json +{ + "$schema": "https://raw.githubusercontent.com/badlogic/pi-mono/main/packages/coding-agent/theme-schema.json", + "name": "my-theme", + "vars": { + "accent": "#00aaff", + "muted": 242 + }, + "colors": { + "accent": "accent", + "muted": "muted", + "text": "", + "userMessageBg": "#2d2d30", + "toolSuccessBg": "#1e2e1e" + } +} +``` + +- `name` is required and must be unique. +- `vars` is optional. It lets you reuse colors. +- `colors` must define all required tokens. + +See [theme.md](theme.md) for the full token list, color formats, and validation details.