190 lines
8.3 KiB
Markdown
190 lines
8.3 KiB
Markdown
---
|
|
created: 2026-05-16
|
|
modified: 2026-05-16
|
|
type: note
|
|
tags:
|
|
- ai
|
|
- dev-ops
|
|
aliases: []
|
|
---
|
|
|
|
# Pi Agent Extensions & Skills
|
|
|
|
## Source Repositories
|
|
|
|
| Source | Location |
|
|
|---|---|
|
|
| Gitea (package) | `git:https://gitea.lab.audasmedia.com.au/sam/pi-config` |
|
|
| Local filesystem | `~/.agents/` |
|
|
| Project settings | `sys_config/.pi/settings.json`, `ai_setup/.pi/settings.json` |
|
|
|
|
---
|
|
|
|
## Extensions
|
|
|
|
| Extension | Source | Purpose |
|
|
|---|---|---|
|
|
| **pi-config** | `~/.agents` | `/config-add`, `/config-remove`, `/config-show`, `/config-setup` — manage which extensions/skills are active in a project |
|
|
| **tavily-search** | Gitea | `tavily_search` — web search via Tavily API (AI-optimized) |
|
|
| **web-fetch** | `~/.agents` | `web_fetch` — fetch any URL and return clean markdown (HTML, PDF, JS-rendered with Jina fallback) |
|
|
| **ask-user-question** | `~/.agents` | `ask_user_question` — LLM presents structured multiple-choice / text questions with keyboard UI |
|
|
| **video-extract** | `~/.agents` | `video_extract` — extract frames from YouTube/local video + full Gemini analysis (requires ffmpeg + yt-dlp + GEMINI_API_KEY) |
|
|
| **filechanges** | `~/.agents` | `/filechanges`, `/filechanges-accept`, `/filechanges-decline` — tracks every file LLM edits/writes, diff review, revert |
|
|
| **pi-subagents** (tintinweb v0.7.1) | `~/.agents` | Spawn child Pi agents for delegated tasks (scout, researcher, worker) |
|
|
| **pi-prompt-template-model** | npm (global) | Model-switching prompt templates with frontmatter. See [[#Prompt Templates]] section below |
|
|
| **pi-graphify** | `~/.agents` | Knowledge graph tools: build, query, path tracing, explain, watch, add, update |
|
|
| **plannotator** | `~/.agents` | Interactive plan review with browser UI, annotations, code review |
|
|
| **caveman** | `~/.agents` | Ultra-compressed communication mode |
|
|
|
|
---
|
|
|
|
## Skills
|
|
|
|
| Skill | Purpose |
|
|
|---|---|
|
|
| **nixos-workflow** | STRICT workflow for managing Pi assets via Gitea on NixOS |
|
|
| **system-architect** | Multi-machine NixOS infrastructure (Snapcast, MQTT, Docker, Nvim) |
|
|
| **obsidian-cli** | Interact with Obsidian vault (notes, search, plugin dev, theme dev) |
|
|
| **graphify** | Full-pipeline knowledge graph orchestration |
|
|
| **caveman** | Caveman communication mode |
|
|
| **openspec-propose** | Propose new changes with design docs, specs, tasks |
|
|
| **openspec-apply-change** | Implement tasks from an OpenSpec change |
|
|
| **openspec-archive-change** | Archive completed changes |
|
|
| **openspec-explore** | Explore ideas and clarify requirements |
|
|
|
|
---
|
|
|
|
## Prompt Templates
|
|
|
|
Prompt templates are `.md` files in `~/.pi/agent/prompts/` with YAML frontmatter. Each defines a slash command that auto-switches model, thinking level, and injects skills — then restores your previous model when done.
|
|
|
|
### Installed Templates
|
|
|
|
| Command | Tier | Model | Use |
|
|
|---|---|---|---|
|
|
| `/quick` | ⚡ flash | deepseek-v4-flash | General everyday tasks |
|
|
| `/think` | 🧠 ultra | openrouter/deepseek-pro | Deep thinking, hard problems |
|
|
| `/check` | 🔷 pro | opencode-go/deepseek-pro | Code review, quality checks |
|
|
| `/nix-check` | ⚡ flash | deepseek-v4-flash | Nix flake checks, config debug |
|
|
| `/note` | ⚡ flash | deepseek-v4-flash | Create Obsidian .md with frontmatter |
|
|
| `/sort` | 🔷 pro | opencode-go/deepseek-pro | Classify files, suggest Obsidian folder |
|
|
| `/read` | ⚡ flash | deepseek-v4-flash | Batch read and synthesize many files |
|
|
| `/debug` | 🧠 ultra | openrouter/deepseek-pro | Complex NixOS/infra debugging |
|
|
| `/vault` | 🔷 pro | opencode-go/deepseek-pro | Obsidian vault setup and management |
|
|
| `/chat` | ⚡ flash | deepseek-v4-flash | Chat with automatic web search |
|
|
| `/img` | 🧠 ultra | openrouter/deepseek-pro | Image analysis and description |
|
|
| `/make-img` | ⚡ flash | deepseek-v4-flash | Generate images via OpenRouter API (Flux/Stable Diffusion) |
|
|
|
|
> **Audio/Voice note:** Pi runs in a text-based terminal (TUI) with no microphone access or audio playback. Qwen supports audio processing, but it's not practical in Pi's current architecture regardless of model.
|
|
|
|
### How to use
|
|
|
|
```
|
|
/quick what's the weather?
|
|
/think design the architecture for this feature
|
|
/check review the changes in this file
|
|
/nix-check analyze the nix flake check output
|
|
/note document the new service setup
|
|
/sort read this config file and tell me where it goes
|
|
/read skim these three config files and compare them
|
|
/debug why is my NixOS build failing?
|
|
/vault set up a template for daily notes
|
|
/chat what's new in NixOS 25.11?
|
|
/img what's wrong in this screenshot?
|
|
/make-img a futuristic cityscape with neon lights
|
|
```
|
|
|
|
### Template format
|
|
|
|
```yaml
|
|
---
|
|
description: Quick task — fast model, minimal thinking
|
|
model: openrouter/deepseek-v4-flash
|
|
restore: true
|
|
---
|
|
$@
|
|
```
|
|
|
|
Key frontmatter fields:
|
|
- **`model`** — provider/model-id or comma-separated fallback list
|
|
- **`thinking`** — off, minimal, low, medium, high, xhigh
|
|
- **`restore`** — (default true) restore previous model when done
|
|
- **`skill`** — auto-inject a skill
|
|
- **`deterministic`** — run a command/script before the LLM turn (e.g. `nix eval .#checks`)
|
|
|
|
### Adding new templates
|
|
|
|
Create a new `.md` file in `~/.pi/agent/prompts/` with frontmatter. The filename becomes the command name. Restart Pi or run any extension command to pick them up.
|
|
|
|
---
|
|
|
|
## Configuration Files
|
|
|
|
### Global (`~/.pi/agent/settings.json`)
|
|
- Nix store symlink — managed via `/etc/nixos/home/sam/home.nix`
|
|
- Contains: providers (opencode-go, openrouter, google), packages (pi-memctx, pi-prompt-template-model, Gitea)
|
|
- **Read-only** — cannot be modified by `pi install` or `/config-add`
|
|
|
|
### Project (`<project-dir>/.pi/settings.json`)
|
|
- Overrides global settings (arrays replace, not merge)
|
|
- Contains: `~/.agents` package (extensions + skills), Gitea package (tavily-search)
|
|
- Modified via `/config-add` / `/config-remove` commands
|
|
|
|
### Per-folder Memory (via pi-memctx)
|
|
- Memory stored in `<chat-folder>/.pi/memory-vault/packs/`
|
|
- Workspace map at `~/.pi/agent/memory-vault/00-system/workspace-map.json`
|
|
- Each chat folder has isolated memory (prevents sibling directory contamination)
|
|
|
|
---
|
|
|
|
## Useful Commands
|
|
|
|
| Command | What it does |
|
|
|---|---|
|
|
| `/quick <task>` | Fast model for everyday tasks |
|
|
| `/think <task>` | Ultra model for deep analysis |
|
|
| `/check <path>` | Pro model for code review |
|
|
| `/nix-check <task>` | Nix-specific analysis |
|
|
| `/note <description>` | Create Obsidian note with frontmatter |
|
|
| `/sort <path>` | Classify file, suggest Obsidian folder |
|
|
| `/read <paths>` | Batch read and synthesize files |
|
|
| `/debug <issue>` | Complex NixOS/infra debugging |
|
|
| `/vault <task>` | Obsidian vault setup and management |
|
|
| `/chat <topic>` | Conversation with web search |
|
|
| `/img <prompt>` | Image analysis and description |
|
|
| `/make-img <prompt>` | Generate image via OpenRouter API |
|
|
| `/config-setup` | One-shot: creates `.pi/`, `settings.json`, memory vault in current folder |
|
|
| `/config-add ext <name>` | Activate an extension from `~/.agents` |
|
|
| `/config-add skill <name>` | Activate a skill from `~/.agents` |
|
|
| `/config-show` | Show active extensions and skills |
|
|
| `/memctx-init` | Scan folder, build initial memory pack |
|
|
| `/memctx-status` | Show memory status |
|
|
| `/memctx-refresh` | Re-scan and enrich memory |
|
|
| `/filechanges` | Review changed files, diffs, accept/decline |
|
|
| `/filechanges-accept` | Accept all changes |
|
|
| `/filechanges-decline` | Revert all changes |
|
|
|
|
---
|
|
|
|
## Skipped / Bookmarked
|
|
|
|
| Extension/Skill | Reason |
|
|
|---|---|
|
|
| **web-search** (amosblomqvist) | ❌ Redundant — Tavily does this |
|
|
| **subagents** (amosblomqvist) | ❌ Redundant — pi-subagents already installed |
|
|
| **bash-guard** (amosblomqvist) | ❌ Too aggressive — would interrupt flow |
|
|
| **google-image-search** (amosblomqvist) | ❌ Would need Google Search API + CSE setup |
|
|
| **pdf-reader** (amosblomqvist) | ⏳ Bookmarked — Python + pymupdf setup needed |
|
|
| **notify** (mitsuhiko) | ⏳ Minor QoL — desktop notifications on task complete |
|
|
| **audio/voice** | ⏳ Not practical | Pi TUI has no mic access or audio playback — fundamental platform limitation |
|
|
|
|
---
|
|
|
|
## Tasks
|
|
|
|
- [ ] Rebuild NixOS to activate Google provider + ffmpeg/yt-dlp + pi-prompt-template-model
|
|
- [ ] Run `/reload` in Pi to activate filechanges and new templates
|
|
- [ ] Add more prompt templates to `~/.pi/agent/prompts/` as needed
|
|
- [ ] Verify video-extract works with Gemini
|
|
- [ ] Clean up workspace-map.json entries for any stale memory packs
|