Skip to content

Repository files navigation

pi-dev-config

Reproducible Pi configuration. Clone, install, and run anywhere with the same extensions, skills, and rules.

pi-dev-config screenshot

CI

Contents

Quick Start

# Clone
git clone git@github.com:docg1701/pi-dev-config.git ~/dev/pi-dev-config

# Install extensions
pi install npm:pi-subagents
pi install npm:pi-prompt-template-model
pi install npm:pi-agent-browser-native
pi install npm:pi-mcp-adapter
pi install npm:pi-smart-fetch
pi install npm:pi-glance
pi install npm:@eko24ive/pi-ask
pi install npm:@leonardorick/pi-web-search
pi install npm:pi-working-vibe
pi install npm:@dietrichgebert/ponytail
pi install npm:@victor-software-house/pi-curated-themes

# Install skills
npx skills add https://github.com/upstash/context7 --skill find-docs
npx skills add https://github.com/199-biotechnologies/claude-deep-research-skill --skill deep-research
npx skills add https://github.com/vercel-labs/skills --skill find-skills
npx skills add https://github.com/streamlit/agent-skills --skill developing-with-streamlit
npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill ansible-automation
npx skills add https://github.com/coreyhaines31/marketingskills --skill product-marketing
npx skills add https://github.com/obra/superpowers --skill systematic-debugging
npx -y skills add liustack/modlens

# Install the ModLens CLI (the skill install adds only the skill, not the binary)
npm i -g @liustack/modlens

# Configure modlens: copy the bundled config template and replace the key
# (free key from https://ollama.com/account/keys)
cp ~/dev/pi-dev-config/modlens-config.example.json ~/.modlens/config.json
# then edit ~/.modlens/config.json: replace <YOUR_OLLAMA_API_KEY> with your key

# Copy APPEND_SYSTEM.md to extend the agent's system prompt
cp ~/dev/pi-dev-config/APPEND_SYSTEM.md ~/.pi/agent/APPEND_SYSTEM.md

# Copy custom vibe files
cp ~/dev/pi-dev-config/vibes/*.txt ~/.pi/agent/vibes/

# Copy settings
cp ~/dev/pi-dev-config/settings.json ~/.pi/agent/settings.json

# Reload pi
# /reload

Skills

Skills.sh registry

Name Description Install
find-docs Library docs via Context7 CLI. Prefer over web search. npx skills add https://github.com/upstash/context7 --skill find-docs
deep-research 8-phase citation-backed research. Quick/standard/deep/ultradeep. npx skills add https://github.com/199-biotechnologies/claude-deep-research-skill --skill deep-research
find-skills Discover and install skills from the open skills ecosystem. npx skills add https://github.com/vercel-labs/skills --skill find-skills
developing-with-streamlit Official Streamlit routing skill: creation, editing, debug, styling, performance, themes, deploy, and custom components. npx skills add https://github.com/streamlit/agent-skills --skill developing-with-streamlit
ansible-automation Infrastructure automation with Ansible playbooks, roles, and inventory. npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill ansible-automation
product-marketing Create .agents/product-marketing.md (foundational positioning/messaging). Use first before other marketing skills. npx skills add https://github.com/coreyhaines31/marketingskills --skill product-marketing
systematic-debugging 4-phase root-cause debugging. Includes root-cause-tracing, defense-in-depth, condition-based-waiting. npx skills add https://github.com/obra/superpowers --skill systematic-debugging
modlens Vision bridge for text-only models — converts images into structured JSON evidence (OCR, layout, semantics, uncertainty). npx -y skills add liustack/modlens
ask-user Reinforces when to use ask_user for structured clarification instead of guessing. Bundled with @eko24ive/pi-ask

Marketing suite

All from coreyhaines31/marketingskills. Install the full suite with npx skills add https://github.com/coreyhaines31/marketingskills --skill product-marketing.

Name Description
product-marketing Foundational positioning and messaging context. Use first.
marketing-ideas 139 proven marketing ideas for SaaS.
content-strategy Plan content strategy, topic clusters, editorial calendar, and content pillars.
copywriting Write or improve marketing copy for homepages, landing pages, pricing, and product pages.
copy-editing Edit, review, and tighten existing marketing copy.
seo-audit Technical and on-page SEO audits; diagnose ranking issues.
programmatic-seo Create SEO-driven pages at scale using templates and data.
ai-seo Optimize content for AI search engines and LLM citations.
schema Add, fix, or optimize schema markup and structured data.
site-architecture Plan and restructure page hierarchy, navigation, URL structure, and internal linking.
analytics Set up, improve, or audit analytics tracking (GA4, GTM, Mixpanel, Segment).
ab-testing Plan, design, and implement A/B tests and growth experiments.
cro Conversion rate optimization for landing pages, forms, and marketing pages.
signup Optimize signup, registration, and trial activation flows.
onboarding Optimize post-signup onboarding, user activation, and time-to-value.
paywalls Create and optimize in-app paywalls, upgrade screens, and upsell modals.
churn-prevention Build cancellation flows, save offers, dunning, and retention strategies.
pricing Pricing decisions, packaging, and monetization strategy.
ads Paid advertising campaigns (Google Ads, Meta, LinkedIn, Twitter/X).
ad-creative Generate and iterate ad copy, headlines, and creative variations at scale.
social Social media content creation, scheduling, and optimization.
video Create and produce video content with AI tools and programmatic frameworks.
image Create, generate, edit, or optimize marketing images and brand assets.
emails Email sequences, drip campaigns, lifecycle email programs, and nurture flows.
cold-email B2B cold emails and follow-up sequences that get replies.
sms SMS/MMS marketing flows, abandoned cart texts, and promotional sends.
popups Popups, modals, overlays, slide-ins, and banners for conversion.
lead-magnets Create and optimize lead magnets for email capture and lead generation.
free-tools Plan and build free tools for lead generation, SEO value, and brand awareness.
directory-submissions Submit product to startup/SaaS/AI directories for backlinks and discovery.
referrals Create and optimize referral, affiliate, and word-of-mouth programs.
co-marketing Find co-marketing partners and plan joint campaigns.
community-marketing Build and leverage online communities for product growth and brand loyalty.
competitor-profiling Research, profile, and analyze competitors from their URLs.
competitors Create competitor comparison and alternative pages for SEO and sales enablement.
prospecting Find, qualify, and build lists of B2B prospects.
sales-enablement Create sales collateral, pitch decks, one-pagers, objection handling, and demo scripts.
revops Revenue operations, lead lifecycle management, and marketing-to-sales handoff.
customer-research Conduct, analyze, and synthesize customer research, interviews, and surveys.
aso Audit and optimize App Store and Google Play listings.
marketing-psychology Apply psychological principles and behavioral science to marketing.
launch Product launch, feature announcement, and release strategy.

Other official registries

  • Anthropic Skills — document processing, web dev.
  • Pi Skills — web search, browser automation, Google APIs, transcription.

Extensions

Name Description Install
pi-subagents Delegate tasks to subagents with chains, parallel execution, TUI clarification, and async support. pi install npm:pi-subagents
pi-prompt-template-model Prompt templates with model/skill frontmatter and slash commands. pi install npm:pi-prompt-template-model
pi-agent-browser-native agent-browser as a native tool. Snapshots, screenshots, sessions. pi install npm:pi-agent-browser-native
pi-mcp-adapter Token-efficient MCP proxy. Lazy servers, cached metadata. pi install npm:pi-mcp-adapter
pi-smart-fetch Smarter web_fetch with TLS fingerprinting and Defuddle extraction. pi install npm:pi-smart-fetch
pi-glance Calm input surface with rounded multiline editor and inline status (model · context · tokens · cost · git). 10 built-in themes. pi install npm:pi-glance
@eko24ive/pi-ask Ask tool with structured questions (single/multi/preview), option notes, elaboration flow, and native @ file references. pi install npm:@eko24ive/pi-ask
@leonardorick/pi-web-search Real DuckDuckGo web search as a native web_search tool. Companion to pi-smart-fetch. pi install npm:@leonardorick/pi-web-search
@dietrichgebert/ponytail Lazy senior dev mode — writes only what the task needs. Cuts ~54% LOC, ~20% tokens/cost, ~27% time. 100% safe. pi install npm:@dietrichgebert/ponytail

Ponytail

Three levels controlling how aggressively the ladder is enforced:

Level Behavior
lite Build what's asked, suggest the lazier alternative in one line.
full (default) Enforce the ladder: stdlib & native first, shortest working diff.
ultra YAGNI extremist. Delete before add, ship the one-liner, challenge the rest.

Switch with /ponytail lite|full|ultra. Persists per session.

Bundled skills:

Command Purpose
/ponytail-review Code review focused on over-engineering — what to delete, simplify, or replace with stdlib.
/ponytail-audit Full repo audit for bloat — ranked list of what to cut.
/ponytail-debt Harvest ponytail: comments into a debt ledger.
/ponytail-gain Show measured impact scoreboard (LOC, cost, speed).
/ponytail-help Quick-reference card for all commands and levels.

Themes

Name Description Install
@victor-software-house/pi-curated-themes 65 curated dark terminal themes adapted from iTerm2-Color-Schemes to pi's 51-token model. Semantic variants with guaranteed hue separation. pi install npm:@victor-software-house/pi-curated-themes

Select a theme in /settings, or set it in ~/.pi/agent/settings.json:

{
  "theme": "catppuccin-mocha"
}

Available themes include catppuccin-mocha, dracula, gruvbox-dark, kanagawa-wave, everforest-dark-hard, lovelace, mellow, vesper, and 57 others. See the full curated list.

Settings & Models

Pi looks for a single file at ~/.pi/agent/settings.json. The destination file must always be named settings.json — pi does not read any other filename directly.

cp ~/dev/pi-dev-config/settings.json ~/.pi/agent/settings.json
# /reload

Model catalog

This repository uses pi's built-in opencode-go and deepseek providers — no extra extension required. The roles below match the Subagent models table.

Model Params Vision Thinking Context Role
minimax-m3 undisclosed yes yes 512K Planner, reviewer
nemotron-3-ultra 550B no yes 256K Disabled by default — see Troubleshooting; re-test target 2026-06-11
deepseek-v4-pro undisclosed no yes 512K Worker, oracle
deepseek-v4-flash 158B no yes 1M Default model; scout, researcher, context-builder
kimi-k2.7-code 1.04T yes yes 256K Delegate

Also enabled (no fixed role, pick via /model): opencode-go/kimi-k3, opencode-go/qwen3.7-plus, opencode-go/qwen3.7-max, opencode-go/minimax-m3, opencode-go/kimi-k2.7-code, deepseek/deepseek-v4-pro.

Note: The default model is deepseek-v4-flash with defaultThinkingLevel: "max". For deepseek*, xhigh maps to max thinking effort (graduated). For minimax*, kimi*, and nemotron* it is effectively a no-op because those models expose thinking as a binary toggle, not a graduated effort level.

⚠️ Context window may not match vendor specs. The values above are what pi currently sees from the providers; vendors advertise larger windows:

Model Vendor advertised Current Source
deepseek-v4-pro 1M 512K DeepSeek-V4 Pro model card
minimax-m3 1M (guaranteed minimum per the vendor) 512K MiniMax docs
nemotron-3-ultra 1M 256K NVIDIA Nemotron 3 Ultra

If a provider raises a limit, re-verify the value (e.g. via its /api/show endpoint) and update the Context column. If a model stops being available, re-validate the subagent mappings in Subagent models.

Subagent models

Subagent Model Thinking
scout deepseek-v4-flash (fast) xhigh
planner minimax-m3 xhigh
worker deepseek-v4-pro xhigh
reviewer minimax-m3 xhigh
oracle deepseek-v4-pro xhigh
context-builder deepseek-v4-flash xhigh
researcher deepseek-v4-flash xhigh
delegate kimi-k2.7-code xhigh

Thinking rules

Per family, sourced from each creator's official docs:

  • deepseek*xhigh. The DeepSeek API docs define exactly two effort levels — high and max — and document that xhigh maps to max. Default is high; complex agent requests (Claude Code, OpenCode) are auto-promoted to max. The DeepSeek-V4 model card shows measurable gains from max over high on agentic benchmarks (Apex 27.4→38.3, BrowseComp 53.5→73.2, LiveCodeBench 88.4→91.6 for V4-Flash). This config runs agentic loops, so xhigh is the right level.
  • glm-5.2xhigh. GLM-5.2 is the first in the GLM family to support reasoning_effort. Values: max (default, recommended), xhigh, high, medium, low, minimal, none. xhigh maps to max; low/medium map to high. Use xhigh for agentic workloads.
  • minimax*, nemotron*, kimi*, glm-5high. The creator docs for MiniMax M3, NVIDIA Nemotron 3 Ultra, Kimi K2.7 Code, and GLM-5.1 expose thinking as a binary on/off toggle, not as a graduated effort level. The providers pass max for xhigh to the OpenAI-compat endpoints, but those models do not differentiate between high and max — the parameter is effectively a no-op. Use high to keep the config honest; pushing to xhigh is wasted quota.
  • The default model (deepseek-v4-flash) sits at max via defaultThinkingLevel. For DeepSeek this maps to the documented max effort; the setting stays at max so that switching the default model to a glm-5.2 does not silently downgrade thinking effort.

Provider Setup

OpenCode Go + DeepSeek

Models come from pi's built-in opencode-go (OpenCode gateway) and deepseek providers — no extension needed.

Setup:

# 1. Add API keys to ~/.pi/agent/auth.json:
# { "opencode-go": { "type": "api_key", "key": "..." },
#   "deepseek":    { "type": "api_key", "key": "..." } }

# 2. The `enabledModels` list in settings.json controls which models appear in /model

Switch models with /model or Ctrl+L. Provider-qualified names (e.g. opencode-go/deepseek-v4-flash) work alongside bare names.

ModLens (Vision Bridge)

ModLens gives text-only models (e.g. deepseek-v4-flash and other models without vision) vision capabilities. It hands images to a real vision engine and returns structured JSON evidence — every word transcribed, layout regions in reading order, semantics, and explicit uncertainty — that the model can quote instead of guessing.

Setup:

# 1. Install the skill (agent trigger: pasted images and image paths)
npx -y skills add liustack/modlens

# 2. Install the CLI — the skill install does not include the binary
npm i -g @liustack/modlens

# 3. Configure the vision provider — copy the bundled config and set your key
#    (free key from https://ollama.com/account/keys)
#
#    ⚠️ Naming trap: the provider is called "openai" in modlens because it accepts
#    ANY OpenAI-compatible endpoint. The template points it at ollama.com — NOT
#    api.openai.com — so the key must be from ollama.com, never from OpenAI.
cp ~/dev/pi-dev-config/modlens-config.example.json ~/.modlens/config.json
# then edit ~/.modlens/config.json: replace <YOUR_OLLAMA_API_KEY> with your key

# 4. Verify
modlens -i some-image.png

Default provider (this repo's setup): openai → Ollama Cloud with minimax-m3 — validated 2026-08-05, ~5s/image, OCR exact, zero extra cost (free ollama.com API key).

Alternatives: gemini-api (free AI Studio key, but rate-limits with 503s under load — keep as fallback with -p gemini-api), antigravity-cli (no key needed, 15–40s, tight weekly quota), anthropic/claude-cli (rides a Claude login, 20–45s). The skill's CLI default is antigravity-cli; modlens config set provider overrides it.

Pasted images: the skill's recover-paste pulls images pasted into the chat out of the harness's session storage (pi stores them in ~/.pi/agent/sessions/) — no need to save a file first.

Automatic trigger: APPEND_SYSTEM.md ships a VISION rule that forces text-only models to load the modlens skill whenever an image appears. Without it, models may not trigger the skill on their own (pi loads skills on demand; the model decides). If you skip the rule, expect to prompt the model explicitly (/skill:modlens or "use modlens on this image").

Working Vibes

pi-working-vibe replaces pi's default Working… message with themed flavor text that rotates while the agent thinks, and auto-switches per tool (bash, read, edit, write, grep, find, ls, web_search, web_fetch, todo).

This repo includes four custom vibe files:

Theme File Phrases Flavor
startrek vibes/startrek.txt 99 Engaging warp drive, scanning for lifeforms...
klingon vibes/klingon.txt 26 Qapla'! bortaS bIr jablu'DI'... (with translation)
dadjokes vibes/dadjokes.txt 200+ Hi Hungry, I'm Dad... Surely you can't be serious...
bbs vibes/bbs.txt 52 NO CARRIER... l33t skillz... RTFM...

Setup

# 1. Install the extension
pi install npm:pi-working-vibe

# 2. Copy custom vibe files to your global config
cp ~/dev/pi-dev-config/vibes/*.txt ~/.pi/agent/vibes/

# 3. Copy settings
cp ~/dev/pi-dev-config/settings.json ~/.pi/agent/settings.json

# 4. Reload pi
# /reload

settings.json is pre-configured with workingVibe: true and workingVibeName: "startrek". Bundled themes from the extension (mafia, hacker, pirate, zen) remain available — switch with /vibe vibe:<name>.

Vibe file format

Vibe files are plain text. One phrase per line, terminating in .... # for comments. Optional [section] headers split lines into pools:

# startrek.txt
Engaging warp drive...
Scanning for lifeforms...

[tool:bash]
Diverting power to shields...

[tool:read]
Extending sensor pallets...

Pools fall back to [default] when the active tool has no dedicated section. Files without headers become one big default pool (backward compatible).

Commands

Command Effect
/vibe Toggle master switch
/vibe on / /vibe off Enable / disable
/vibe list List installed vibes (user + bundled)
/vibe info Show active settings + line counts
/vibe pools List sections in the active vibe
/vibe preview Pick a sample line from the active pool
/vibe reload Re-read settings + vibe file from disk
/vibe vibe:<name> Switch active vibe
/vibe indicator:<preset> default | dots | line | pulse | braille | arrow | custom
/vibe color:<token> Theme color for spinner (e.g. accent, primary, dim)
/vibe rotate:<ms> Message rotation interval (0 = static)
/vibe interval:<ms> Spinner frame interval

Switching themes

/vibe vibe:startrek     # Back to Starfleet
/vibe vibe:klingon      # Qapla'! — Klingon with translations
/vibe vibe:dadjokes     # Hi Hungry, I'm Dad...
/vibe vibe:bbs          # NO CARRIER...
/vibe vibe:mafia        # Bundled with the extension
/vibe off               # Disable vibes

User files in ~/.pi/agent/vibes/ override bundled files of the same name, so you can fork startrek.txt without losing package updates.

Settings reference

Key Type Default Effect
workingVibe boolean true Master switch
workingVibeName string "mafia" Vibe file name (no .txt)
workingVibeRotateMs number 3500 Rotation interval; 0 = static. Floor 750ms
workingIndicator enum "default" Spinner preset
workingIndicatorColor string "accent" Theme color token
workingIndicatorFrames string[] [] Custom frames (when workingIndicator: "custom")
workingIndicatorIntervalMs number 90 Spinner frame interval. Floor 40ms

Ghostty

Terminal configuration for development with pi.

File Description
ghostty/config.ghostty GitHub Dark theme, JetBrains Mono 12px, blinking bar cursor, padding 8x4, shell integration
ghostty/SSH_NERD_FONT.md Guide for Nerd Font icons to work over SSH (Ghostty → VPS)

To enable Nerd Font icons in the status line over SSH, add TERM_PROGRAM TERM_PROGRAM_VERSION to the sshd AcceptEnv on the VPS — see ghostty/SSH_NERD_FONT.md.

cp ~/dev/pi-dev-config/ghostty/config.ghostty ~/.config/ghostty/config.ghostty

Restart Ghostty completely after copying.

Context & Rules

Pi loads two kinds of instruction files at startup:

File Scope Purpose
APPEND_SYSTEM.md Global (~/.pi/agent/) Extends the system prompt — behavioral rules and conventions that apply to every session (code style, testing, logging, etc.). Appended without replacing the native prompt.
AGENTS.md Per-project Project-level context — stack, conventions, build commands, and local rules. Pi concatenates all AGENTS.md found from cwd up through parent directories plus ~/.pi/agent/.

This repo ships a reusable APPEND_SYSTEM.md with language-agnostic coding rules. Copy it once to your global config. For project-specific instructions, create AGENTS.md at the project root — no example is included because it should be customized per project (tech stack, build commands, team conventions).

AGENTS.md best practices

See docs/research/AGENTS.md-analysis-20260529.md for a comprehensive research report (14 sources, 6 core areas). Key takeaways:

  • 6 core areas every AGENTS.md should cover: Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries.
  • Commands at the top with exact flags, copy-pasteable — highest-ROI section.
  • Boundaries with 3 levels (Always / Ask first / Never) — single most effective constraint pattern.
  • Code examples over descriptions — one real snippet beats three paragraphs.
  • ≤150–180 lines is the sweet spot — every extra line consumes context tokens.
  • No changelog or human documentation — AGENTS.md is a runtime instruction set; README.md is for humans.

CI & Validation

.github/workflows/ci.yml runs on every push, PR, and v*.*.* tag.

  • validate job — runs validate.py on every change. Validates that all JSON, TOML, and Markdown files in the repo parse correctly and that settings.json has the required keys (packages, defaultProvider, defaultModel, enabledModels).
  • release job — fires only on v*.*.* tags. Categorizes the commits since the previous tag into Added (feat), Fixed (fix), and Changed (chore/docs/ci/refactor/style/test/perf/revert/build), and creates a GitHub release with auto-generated notes.

Run validate.py locally before pushing:

python3 validate.py

See docs/ci-auto-release-guide.md for the full release workflow.

Repository Structure

pi-dev-config/
├── APPEND_SYSTEM.md               # Global system-prompt rules and conventions
├── settings.json                  # Pre-configured pi settings (OpenCode Go + DeepSeek providers)
├── modlens-config.example.json    # ModLens config template (openai → ollama.com, minimax-m3)
├── validate.py                    # Local pre-push validator (JSON/TOML/Markdown)
├── VERSION                        # Current release version (single source of truth)
├── assets/                        # Static assets (images, etc.)
├── .github/
│   └── workflows/
│       └── ci.yml                 # CI: validate on push/PR, auto-release on tags
├── docs/
│   ├── ci-auto-release-guide.md         # Full release workflow guide
│   ├── DESIGN.md                        # Cal.com design system analysis (Dembrandt)
│   ├── PI_DEV_CHEATSHEET_EN.md          # Practical workflow guide (EN)
│   ├── streamlit_pro_tips.md            # 25+ Streamlit PRO tips from official video
│   ├── streamlit_extras_guide.md        # streamlit-extras complete reference guide
│   └── research/
│       └── AGENTS.md-analysis-20260529.md  # AGENTS.md industry standard research (14 sources)
├── ghostty/
│   ├── config.ghostty             # GitHub Dark, JetBrains Mono, shell integration
│   └── SSH_NERD_FONT.md           # Nerd Font icons over SSH guide
├── vibes/
│   ├── startrek.txt               # Startrek: 99 phrases
│   ├── klingon.txt                # Klingon + translations: 26 phrases
│   ├── dadjokes.txt               # Dad jokes: 200+ phrases
│   └── bbs.txt                    # BBS taglines 90s: 52 phrases
└── README.md                      # This file

Troubleshooting

nemotron-3-ultra: past incident and re-test plan

  • 2026-06-04 (first deploy): Nemotron-3-ultra was deployed as worker + researcher. It burned ~20M tokens across 29 requests and drained the Pro quota. Ollama Cloud subsequently reset session and weekly usage counters (observed same day), suggesting a provider-side fix for a runaway thinking loop.

  • 2026-06-04 (re-deploy attempt): Re-deployed after the Ollama Cloud reset. The runaway recurred. Nemotron-3-ultra was removed from enabledModels; worker + researcher reverted to M3.

  • Re-test target: 2026-06-11 (one week after the second removal). To re-enable for testing, set the following in agentOverrides and add "nemotron-3-ultra" back to enabledModels:

    "worker":     { "model": "nemotron-3-ultra", "thinking": "high" },
    "researcher": { "model": "nemotron-3-ultra", "thinking": "high" }

    If the runaway recurs on the re-test: pull nemotron again and push the re-test target by another week. The trigger is a single request burning >1M tokens, or Pro quota dropping by more than 10% in one worker run.

License

MIT

About

Reproducible Pi.dev configuration with skills, extensions, and agent rules

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages