Observed practice
Learn the core loop interactively, then branch out
Most users should start in the TUI and only move into JSON mode, RPC, or SDK embedding once they understand how Pi sessions, context, and extensions actually behave.
Reading rule
Separate what the ecosystem does from what you should copy
This page now distinguishes observed practice from recommended practice so a deeper reader can tell evidence from judgment quickly.
Current editorial need: orientation plus practical entry points. That means the site tries to preserve real ecosystem behavior without pretending every repeated pattern is automatically a good default.
Observed practice
Patterns that actually keep showing up
Observed practice
Package the way you work
Once something is useful twice, the Pi ecosystem tends to turn it into a skill, extension, prompt template, theme, or npm/git package rather than keeping it as a private prompt trick.
Observed practice
Script the agent through JSON, RPC, or SDK
A big part of Pi's distinctiveness is that it can stop being a chat app and become infrastructure for bots, scripts, or embedded tooling.
Observed practice
Operate through worktrees or queues
When a single session stops scaling, Pi users either wrap it in queue-first review lanes or in shell-native worktree swarms; both paths show up clearly in the ecosystem.
Observed practice
Think “programmable harness,” not “finished assistant”
Pi makes more sense once you stop asking what features it is missing and start asking what primitives it exposes: modes, context hooks, extensions, packaging, and session control.
Observed practice
Learn the packaging story early
The ecosystem’s leverage comes from reusable skills, extensions, prompt templates, and npm/git-distributed packages. That packaging layer matters more than any one theme or slash command.
Recommended practice
Defaults that seem strongest right now
Recommended practice
Start with the four Pi modes before shopping for add-ons
Pi already spans interactive TUI, print/JSON, RPC, and SDK embedding. A lot of ecosystem confusion comes from treating everything as “more features” instead of choosing the right mode first.
Recommended practice
Prefer packages you can inspect, clone, and version
The healthiest Pi patterns are visible assets—skills, extensions, templates, themes, and package folders—not giant invisible prompts. They are easier to share, diff, adapt, and remove.
Recommended practice
Treat cross-runtime portability as a design advantage
Pi packages become more durable when they are not trapped in Pi alone. The ecosystem rewards artifacts that can travel to Claude Code, Codex CLI, Amp, or other shells with minimal adaptation.
Recommended practice
Choose your automation branch explicitly
There are at least two distinct Pi escalation paths: queue-first orchestration like Task Factory, and worktree-first shell swarms like PiSwarm. Pick the branch that matches how your team already works.
Recommended practice
Don't confuse power with safety
Pi-adjacent tools can be intentionally permissive. If you are using unattended execution, local credentials, or sensitive repos, add sandboxing, redaction, or policy tooling deliberately instead of assuming it is present.