pi-agent
Helps your agent build and operate a coding environment called Pi. It allows configuring tools, creating extensions, and integrating language models.
What it does
Pi Agent is a tool to help you use and build with Pi, a system for coding in your terminal. It allows you to install, configure, and use Pi for various programming tasks.
When to use it
- ✓When you want to install or configure Pi.
- ✓When creating new extensions or tools for Pi.
- ✓To integrate Pi with other programs or systems.
Example of what to ask your AI
“How do I install Pi and set up my first provider?”
Want more? Open the sections below.
How to use
The easiest way: copy the message below and paste it into Claude, ChatGPT, Cursor or any AI. It reads the skill and follows the instructions.
Skill link
Ready-to-paste message
How it works
Pi Agent understands your instructions to manage Pi. It can install Pi, adjust settings, create new features, or connect Pi to other systems using different communication methods.
Installation
Easiest way: copy the skill link and paste it into Claude, ChatGPT or Cursor asking it to follow the instructions.
In the terminal (Claude Code, Codex, Cursor), in your project folder:
npx skills add K-Dense-AI/scientific-agent-skills --skill pi-agentOr download just the file:
curl -L https://raw.githubusercontent.com/K-Dense-AI/scientific-agent-skills/main/skills/pi-agent/SKILL.md -o SKILL.mdTechnical content (original SKILL.md)
Original text by the author, straight from GitHub.
Pi Agent
Use this skill when the user wants to operate Pi or build on top of Pi. Pi is a minimal terminal coding harness extended through TypeScript extensions, skills, prompt templates, themes, packages, custom models/providers, SDK integrations, RPC mode, JSON event streams, and TUI components.
First Decision
Pick the reference before answering or coding:
| User intent | Read |
|---|---|
| What Pi is, docs map, install methods | references/overview.md |
| Install, authenticate, first run | references/quickstart.md |
| Day-to-day CLI usage, commands, modes, flags, project trust | references/usage.md |
| Provider auth, API keys, cloud provider setup | references/providers.md |
| Custom model entries, local models, proxies, compat flags | references/models.md |
Local llama.cpp router, /llama, model download/load |
references/llama-cpp.md |
| Settings keys and defaults | references/settings.md |
PI_* and other environment variables |
references/environment-variables.md |
| Extension development, custom tools, events, commands | references/extensions.md |
| Custom provider implementation, OAuth, custom streaming | references/custom-provider.md |
| Embed Pi in Node/TypeScript | references/sdk.md |
| Integrate from another process/language | references/rpc.md |
| Consume JSONL event output | references/json.md |
| Build terminal UI components | references/tui.md |
| Package extensions/skills/prompts/themes | references/packages.md |
| Delegate to subagents, chains, parallel runs, orchestration | references/pi-subagents.md |
| Connect MCP servers, codemode, MCP tool discovery/config | references/mcp.md (built-in), references/pi-mcp-adapter.md (optional adapter) |
| Interactive interview forms, structured user input | references/pi-interview.md |
| Web search, URL/PDF/repo fetching, video understanding | references/pi-web-access.md |
| Author Pi skills | references/skills.md |
| Prompt templates or themes | references/prompt-templates.md, references/themes.md |
| Sessions, branching, compaction, parsing JSONL | references/sessions.md, references/compaction.md, references/session-format.md |
| Security, sandboxing, trust | references/security.md, references/containerization.md |
| Keyboard or terminal issues | references/keybindings.md, references/terminal-setup.md, references/tmux.md, references/windows.md, references/termux.md, references/shell-aliases.md |
| Working on Pi itself | references/development.md |
Build-On-Pi Defaults
Prefer the SDK for Node/TypeScript apps that need type safety, direct state access, in-process custom tools/extensions, or custom resource loading. Use createAgentSession() for a single stable session; use createAgentSessionRuntime() when the app must replace sessions through new/resume/fork/clone/import flows. Auth and model lookup go through ModelRuntime.create().
Prefer RPC mode when the client is not Node.js, needs process isolation, or wants a language-agnostic JSONL protocol. Start with pi --mode rpc --no-session for stateless subprocess integration, then add session flags when persistence matters. Split records on \n only — Node readline is not protocol-compliant.
For RPC clients, correlate responses by unique request id, not arrival order,
and keep consuming events after a successful prompt response. Success means
accepted, queued, or handled; it is not completion. Subscribe before sending the
prompt, and wait for agent_settled for runs that actually start, because
agent_end may precede retries or queued work. If the response reports
disposition: "handled", no run started and no settled event is owed. See the
upstream RPC lifecycle.
Prefer JSON mode for one-shot command-line pipelines that only need streamed events, not bidirectional control: pi --mode json "prompt".
Use extensions for Pi-native behavior: custom tools, command handlers, event hooks, provider registration, custom compaction, path protection, project trust policy, UI prompts, widgets, and TUI components.
Use packages when sharing or installing reusable extensions, skills, prompt templates, or themes across machines or projects.
Safety Defaults
…
FAQ
What is Pi?
Pi is a system for coding directly in your terminal, which can be extended with new functionalities.
What are 'providers'?
Providers are like connections that Pi uses to interact with different language models or services, such as API keys.
What do 'RPC' or 'JSON event streams' mean?
These are technical ways for Pi to communicate with other programs, sending and receiving information in specific formats.
Details
Original description by the author
Builds with and operates Pi, the minimal terminal coding harness. Use for installing Pi, configuring providers/models/settings/environment variables, creating Pi skills/extensions/packages/themes/prompt templates, embedding Pi through the SDK, integrating over RPC or JSON event streams, parsing sessions, running local models through the llama.cpp router, developing custom Pi providers and TUI comp
Popularity
- GitHub stars
- 51k
- Ranking position
- #1935
- License
- MIT
- Updated
- 10/15/2026
Comments
- …
More skills from this repository
13c-metabolic-flux
Estimates metabolic fluxes using carbon-13 isotope tracing data. It is useful for analyzing cellular metabolism and biochemical pathways.
K-Dense-AI/scientific-agent-skills
adaptyv
Designs protein characterization experiments using the Adaptyv API. It helps estimate costs, submit sequences, and monitor lab results.
K-Dense-AI/scientific-agent-skills
aeon
Performs machine learning tasks on time series data. It is useful for classifying, forecasting, detecting anomalies, and finding patterns in sequential data.
K-Dense-AI/scientific-agent-skills
alphagenome
Looks up precomputed genomic effects for genetic variants. It provides scores and explanations to understand the impact of variants on the genome.
K-Dense-AI/scientific-agent-skills
Similar skills
benchmark-optimization-loop
Has your agent improve something's speed in a measured way. It tests multiple versions and chooses the fastest one that still works correctly.
affaan-m/ECC
change-impact
Helps your agent analyze the impact of code changes before making them. It compares the planned vs. actual results afterward, covering paths, data, tests, and documentation. Useful for risky or system-wide changes.
affaan-m/ECC
click-path-audit
Lets your agent trace all user buttons and interactions to find bugs. It finds issues where functions seem to work alone but fail together. Useful when bugs persist even after debugging.
affaan-m/ECC