A well-commented, ready-to-use starting point for Pi that helps you actually understand what's happening.
Inspired by kickstart.nvim and the opencode version (kickstart.opencode).
- Philosophy
- Quick start
- Project structure
- How to make it yours
- What this is NOT
- Built-in
- Beautification
- Saving tokens
- Agentic Workflow
- Explore
- Additional features
- AGENTS.md
Most "AI config starter" repos give you a finished product. You get power, but you don't understand what's happening or why.
kickstart.pi does the opposite:
- Every file is short and heavily commented
- Every decision is explained, not just shown
- It's a starting point, not a framework
- You're expected to add your own settings, delete what's unused
- No bundled skills, no bundled agents — you grow into them
Let pi install it for you (recommended)
Paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation.md
Manual installation
⚠️ If~/.pi/agent/already has config, back it up first.
git clone https://github.com/orionpax1997/kickstart.pi ~/.pi/agent
piThen start pi in any project:
cd /path/to/project
pikickstart.pi/
│
├── LICENSE
├── README.md ← you are here
├── README.zh-cn.md ← Chinese version
└── docs/
├── installation.md ← install / backup / update
├── installation-rtk.md ← optional: token-saving bash rewriter (global)
├── installation-caveman.md ← optional: token-saving prose rewriter (project)
├── installation-superpowers.md ← optional: agentic workflow skills (project)
├── installation-openspec.md ← optional: spec-driven dev workflow (project)
├── installation-codegraph.md ← optional: pre-indexed code knowledge graph (project)
├── installation-codebase-memory-mcp.md ← optional: SQLite knowledge graph (project)
├── installation-agent-browser.md ← optional: browser automation via CDP (project)
├── installation-subagents.md ← optional: Claude Code-style sub-agents (global)
├── installation-remote-pi.md ← optional: local agent mesh + mobile app (global)
├── installation-open-tui.md ← optional: animated header + Starship footer + rounded editor (global)
└── installation-themes-bundle.md ← optional: sixteen terminal palettes (global)
That's it. No settings.json, no skills, no agents, no extensions. kickstart.pi is intentionally bare — your model, theme, and other tooling are configured by you in your own ~/.pi/agent/. The only required add-on is the three MCP servers installed via Step 3 of docs/installation.md (context7, searchcode, exa).
- Read
README.mdfrom top to bottom — understand the philosophy and what's available. - Decide what goes in your
~/.pi/agent/settings.json— kickstart.pi ships no config by design. Set your preferred provider, model, and theme. pi walks you through this on first launch. - Install token-savers globally — rtk is the only one recommended at the global level. Compresses verbose bash output across every project.
- Install project-level tools as you need them — codegraph / codebase-memory-mcp for code context, superpowers for skills, OpenSpec for spec-driven dev, caveman for prose compression, agent-browser for browser automation. Each one scopes itself to the project you
cdinto. - Or install global session-level tools — pi-subagents spawns Claude Code-style sub-agents; remote-pi wires up a local agent mesh plus the mobile app. One install covers every project.
- Customize the global
AGENTS.md— add your language preference, working style, and MCP usage hints that apply everywhere. - Add project-level
AGENTS.mdin repos that need it — project structure, tech stack, coding conventions. - Create your own prompt templates in
.pi/prompts/for repetitive workflows (/your-command).
Delete anything you don't use. It's a starting point, not a framework.
- Not a multi-agent orchestration system
- Not a production-ready AI pipeline
- Not something you use without reading
The install flow in docs/installation.md sets up everything kickstart.pi needs to be useful out of the box:
Pi's native model is "no MCP". Pi is built around extensions and skills loaded directly into its own process — MCP isn't part of the core architecture.
Why an MCP bridge ships anyway: the broader agent ecosystem (Context7, SearchCode, Exa, and most third-party agent tools) speaks MCP.
pi-mcp-adapterplus a handful of MCP servers is how kickstart.pi stays compatible with that ecosystem, without taking a stance.
MCP bridge (Step 3 prerequisite):
- pi-mcp-adapter — adapter package that lets pi talk to MCP servers
Three required MCP servers (Step 3):
- context7 — library and framework documentation
- searchcode — public repository code search
- exa — web search (loaded eagerly at session start)
No settings.json shipped — pi walks you through provider / model / theme selection on first launch. If you already have a backup, restore it with cp ~/.pi/agent.bak/settings.json ~/.pi/agent/.
These MCP servers are what the global AGENTS.md points at. Without them, those instructions have nothing to query.
pi-open-tui is a polished TUI styling extension for pi — bundles the best of pi-haiku, pi-claude-code-tui, and pi-zentui into one cohesive package: an animated 16-frame Pi logo header, a two-line Starship-inspired footer (cwd, git branch & status, runtime version, context bar, model, tokens, cost), a rounded editor with accent rail, a working timer, and turn telemetry (TPS / TTFT / stalls / cost) shown as a transient notification after each run. Configure header, footer segments, icon mode, and telemetry from inside pi with /open-tui.
Install at the global level. Paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-open-tui.md
Then /open-tui to toggle the header / footer / rounded editor, switch between Nerd Font and ASCII icons, and configure telemetry segments.
@firstpick/pi-themes-bundle adds sixteen custom terminal palettes to pi's theme picker — dark and light variants of Catppuccin, Dracula, Tokyo Night, Gruvbox, Nord, Rosé Pine, One Dark, Solarized, and Everforest, plus matrix and crimson-noir. Pick one from /settings or set theme in ~/.pi/agent/settings.json.
Install at the global level. Paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-themes-bundle.md
Then /settings to pick a palette, or set theme in ~/.pi/agent/settings.json (e.g. "theme": "tokyo-night").
rtk transparently rewrites verbose shell commands (git status, pnpm list, vitest, cargo test, …) into compact token-saving form. Each pi session is intercepted and rewritten automatically — same workflow, fewer tokens.
Install at the global level. Paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-rtk.md
caveman compresses pi's prose output ~65–75% while preserving technical accuracy. Six intensity levels, triggered by /caveman or keywords like "caveman mode" / "less tokens".
Install at the project level. cd into the project directory first, then paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-caveman.md
superpowers provides a curated skill set for brainstorming, debugging, TDD, planning, code review, and more. Skills auto-load per task — no manual invocation once installed.
Install at the project level. cd into the project directory first, then paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-superpowers.md
OpenSpec is a spec-driven development tool for generating and managing project specifications.
Install at the project level. cd into the project directory first, then paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-openspec.md
codegraph pre-indexes the codebase into a knowledge graph. The agent gets precise context — call chains, blast radius, related symbols — in one query.
Install at the project level. cd into the project directory first, then paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-codegraph.md
codebase-memory-mcp is a single static binary that indexes the codebase into a persistent SQLite knowledge graph (158 languages, 14 MCP tools, millisecond queries). Like codegraph, it gives the agent one call for structured context.
Install at the project level. cd into the project directory first, then paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-codebase-memory-mcp.md
@tintinweb/pi-subagents brings Claude Code-style autonomous sub-agents to pi — spawn specialized agents in isolated sessions, each with its own tools, system prompt, model, and thinking level. Run them in foreground or background, steer them mid-run, and define your own agent types via .pi/agents/*.md (project) or globally.
Install at the global level. Paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-subagents.md
Then /agents to manage and inspect running sub-agents from inside pi.
agent-browser lets the pi agent control a browser via CDP (Chrome DevTools Protocol) — more token-efficient than traditional headless browser approaches.
Install at the project level. cd into the project directory first, then paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-agent-browser.md
remote-pi adds two superpowers on top of pi, wired up by a single /remote-pi slash command: a local agent mesh (open several pi terminals in the same directory and they discover each other over a Unix-domain-socket broker, with two new LLM tools — agent_send and agent_request), and a mobile app that drives pi from your phone via a QR-paired WebSocket relay (send prompts / voice / images, switch model and thinking level). The agent network is purely local; only the mobile relay touches the network, and only through end-to-end-encrypted payloads.
remote-pi is unrelated to pi-subagents: sub-agents are spawned inside one process by the main agent; remote-pi peers are separate pi processes that opt in to a shared mesh and talk to each other directly.
Install at the global level. Paste this into pi:
Read the installation guide and follow it:
https://raw.githubusercontent.com/orionpax1997/kickstart.pi/refs/heads/main/docs/installation-remote-pi.md
Then /remote-pi to run the one-time setup wizard, /remote-pi pair to scan a QR with the Remote Pi app, and /remote-pi status to see who's connected.
AGENTS.md is the global instruction file pi loads into every session. Keep it short — only include what truly applies everywhere.
pi also auto-discovers AGENTS.md / CLAUDE.md walking up from the cwd, so a project-level copy in the project root overrides the global one for that project.
Suggested content for the global file:
- Language preference — e.g.
Reply in Chinese. - MCP usage hints — e.g.
Use context7 to look up library and framework documentation. - Personal coding preferences — e.g.
Never use any type. Prefer explicit types. - Working style — e.g.
Keep responses concise. No need to explain obvious steps.
Project-level AGENTS.md goes in the project root, describing project structure, tech stack, development standards, etc. It overrides the global for that project.