How to Install and Customize Pi Agent Locally

TL;DR

Install Pi globally with the one-line command from pi.dev, launch it by entering “pi” in a terminal, then connect a provider through the login menu. Its minimal design combines four built-in tools with configurable Markdown instructions, model choice, and optional extensions, allowing users to adapt the local agent to personal and project-specific workflows.

Transcript

My name is David Andre and this is a complete course on PI agent. First, what even is PI? PI Agent, also known as PI.dev, is a very simple and customizable AI agent and it's the AI agent I've been using every single day, even more than cloth code and CEX. Also, it's one of the fastest growing repositories in all of GitHub, meaning soon enough, I th... Read More

Key Insights

• • Pi Agent is a minimal and customizable AI-agent harness designed to be adapted to a user’s workflow. The course contrasts this approach with more opinionated products that include many features, safeguards, and built-in conventions for a broad audience.
• • Pi’s system prompt is approximately 1,000 tokens, which the presenter says is 10 to 15 times smaller than those of other agents. Because system-prompt tokens are processed during use, this compact foundation is presented as both efficient and easier to customize.
• • Pi supports more than 15 providers and thousands of AI models, according to the presentation. Users can connect a subscription or API key, then use the model menu to choose among the models exposed by their selected provider.
• • Pi installation starts with the one-line installer command published on pi.dev. After pasting the command into a terminal, the user can start the locally installed agent by entering “pi,” authenticate if necessary, and send an initial prompt to verify the setup.
• • OpenRouter authentication requires an account, available credits, and a newly created API key. The demonstration recommends adding $5 or $10 in credits, optionally applying a spending limit, keeping the key private, and pasting it into Pi when prompted.
• • Pi’s persistent context is controlled through Markdown files. system.md replaces the entire default system prompt, append-system instructions add preferences without discarding the defaults, and an AGENTS.md file supplies context associated with a particular project or working folder.
• • Pi includes four built-in tools: read, write, edit, and bash. These tools cover file inspection, file creation, file modification, and terminal control, while missing capabilities such as web search can be added through extensions when a workflow requires them.
• • Bash gives Pi broad access to tasks available through the terminal. The presenter describes using it for managing files and folders, installing packages, opening or closing applications, inspecting a network, and performing other computer operations that a developer could execute from a terminal.

Questions & Answers

Q: How do you install Pi Agent locally?

Go to pi.dev, scroll to the one-line installer, and copy the displayed command. The presenter chooses the curl version, pastes it into a terminal, and says a first installation takes about 20 seconds. Once installation finishes, enter “pi” in the terminal and press Enter to launch the locally installed agent.

Q: How do you connect Pi Agent to an AI provider?

Launch Pi in a terminal and use the login command if the agent is not already authenticated. The login menu lets you select a provider and choose between an eligible subscription and an API key. In the demonstration, the presenter selects OpenRouter, enters a newly created key, and confirms the connection by sending a simple greeting.

Q: How do you create an OpenRouter API key for Pi Agent?

Sign in at openrouter.ai, open the credits area, and add credits to the account. The presenter says $5 or $10 should be sufficient to begin. Next, open the API Keys section, select the new-key button, name the key, optionally set a spending limit, create it, and copy it into Pi’s authentication prompt.

Q: How do you change models and thinking effort in Pi Agent?

Enter the model command inside Pi to open the model-selection interface and choose another model offered by the connected provider. To change thinking effort, use Shift+Tab to cycle through the available settings described in the transcript: off, minimal, low, medium, high, and extra high. The presenter generally keeps this setting at extra high.

Q: What context files does Pi Agent use?

Pi can obtain persistent context from three main Markdown configurations. system.md replaces the complete default system prompt, while append-system instructions are added after that prompt and preserve its existing behavior. An AGENTS.md file can be placed globally or within a project folder to supply context that should be loaded for sessions in that location.

Q: Should you replace Pi Agent’s default system prompt?

The presenter advises caution with system.md because it overrides the full default system prompt. For ordinary behavioral changes, append-system instructions are presented as the safer option because they add preferences without removing the defaults. Examples include language selection, concise responses, preferred date formatting, and an instruction to relay terminal results in visible text.

Q: What tools are built into Pi Agent?

Pi comes with four built-in tools: read, write, edit, and bash. Read inspects files, write creates them, edit changes existing content, and bash controls the terminal. The presenter argues that these basic tools can support many workflows, but capabilities not included by default, such as web search, must be added separately through extensions.

Q: How do project-specific instructions work in Pi Agent?

Create an AGENTS.md file inside the relevant project or working folder and place the project’s instructions or context there. Pi loads that information when it operates in the project, keeping local requirements separate from global preferences. The transcript also states that Pi can read existing CLAUDE.md files, allowing it to work with projects that already contain those instructions.

Summary & Key Takeaways

• Pi Agent is presented as a minimal, customizable local AI-agent harness rather than a heavily opinionated mass-market product. It has a roughly 1,000-token system prompt, supports more than 15 providers and thousands of models, and lets users shape its behavior around their own workflows instead of accepting a fixed setup.

• Installation begins with the one-line command on pi.dev. After launching Pi from a terminal, users can authenticate through the login menu with a subscription or API key. The demonstration connects OpenRouter, creates a private API key with a spending limit, selects a model, and adjusts thinking effort through keyboard controls.

• Pi receives persistent instructions from Markdown files. Users can append global preferences through append-system instructions or create an AGENTS.md file containing project-specific context. Its four native tools are read, write, edit, and bash, while capabilities such as web search must be introduced separately through extensions.