mirror of
https://github.com/getcompanion-ai/co-mono.git
synced 2026-04-15 19:05:11 +00:00
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
This commit is contained in:
Mario Zechner
parent
27b27d9441
commit
94952bd6c0
4 changed files with 272 additions and 2 deletions
|
|
@ -9,9 +9,11 @@
|
|||
<a href="https://github.com/badlogic/pi-mono/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/badlogic/pi-mono/ci.yml?style=flat-square&branch=main" /></a>
|
||||
</p>
|
||||
|
||||
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
|
||||
|
|
|
|||
158
packages/coding-agent/docs/packages.md
Normal file
158
packages/coding-agent/docs/packages.md
Normal file
|
|
@ -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/<host>/<path>` (global) or `.pi/git/<host>/<path>` (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
|
||||
57
packages/coding-agent/docs/prompt-templates.md
Normal file
57
packages/coding-agent/docs/prompt-templates.md
Normal file
|
|
@ -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 <path>` (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.
|
||||
46
packages/coding-agent/docs/themes.md
Normal file
46
packages/coding-agent/docs/themes.md
Normal file
|
|
@ -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 <path>` (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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue