How to Set Up Pi Coding Agent Like Claude Code

As AI has been growing in popularity, I’ve also seen a growing usefulness in powerful harnesses. Researchers found that using the same model with different harnesses gave an 8.5 to 13 percentage point difference in benchmark results—that means that harnesses are making a significant impact on the results of their code.

The agent that won my time and attention in the end was Pi. Pi is a minimalist AI agent that can be almost completely customized. You can set up your own add-ons, skills, system prompts, and LLM models. The appeal is the ability to have an AI agent that is completely tweaked to suit your exact use cases. Maybe you want more control over the exact token usage of your agent, or maybe you need your AI agent to follow a specific workflow—Pi was built so you can make it whatever you need it to be. The possibilities are endless.

Maybe for this exact reason, it’s easy to get lost with Pi. It has a massive library of add-ons and skills, but which ones should I use? Which ones would be bloat, and which ones improve its performance? I came up with an idea to resolve these issues. I would match the features of Claude Code one-to-one as a baseline for what a generalized coding agent can do.

I chose to match Claude Code’s features because of its massive popularity. But, as I’ve stated before, the main appeal of Pi is how customizable it is to a specific workflow or needs. So—while matching Claude Code one-to-one serves as a good starting point—I wouldn’t recommend that you add any add-on mentioned in this tutorial that you don’t need. Feel free to skip anything that you don't want for your agent. I would also recommend customizing the agent beyond what this tutorial covers. That's the whole appeal of Pi, so don’t limit yourself to what is explained in this tutorial, explore the capabilities of the agent by yourself.

Setup

To start, follow Pi’s quickstart guide. You can choose any model and provider. By default, it should be able to write code relatively well. Now, we’ll work on improving the packages and system prompt.

Packages

Packages are a mix of extensions, themes, skills, and prompts. Packages will be our best way to replicate the functionality of Claude Code. I wanted to match Claude Code’s features as closely as possible. So we’re focusing on replicating these tools: MCP, web search, plan mode, subagents, asking the user questions (such as confirmations or guidance), and LSP information. We’ll go into each package briefly and what each one is supposed to do.

If you don’t want an explanation, you can just install each of the packages.

Ask user questions

The most important package on this list. This allows our agent to ask questions to us, the user. These are often regarding the way a feature should be implemented. Without this, the agent has no way of stopping and making sure that it’s on the correct path. Even if you don’t install any other package, I would recommend that you install at least this one.

The agent should be able to use this package without any configuration from you. Whenever the agent is unsure about what to do, it will consult you.

Install by running:

pi install npm:@juicesharp/rpiv-ask-user-question

Web Access

One of my most used packages. It allows our agent to search the web, extract the content, and process web videos.

This package should work whenever your agent is given a link that is accessible.

Install by running:

pi install npm:pi-web-access

MCP

This MCP package allows our AI agent to interact with external APIs and resources without building specific agentic tools for each of them. A good example is the Chrome MCP server, which allows any AI agent to interact with Chrome as long as it supports MCP.

If you already have MCP set up in ~/.config/mcp/mcp.json or .mcp.json, it should work automatically. Otherwise, follow the quick start guide to get a simple MCP setup going.

Install it by running:

pi install npm:pi-mcp-adapter

Sub Agents

This plugin allows pi to create its own sub-agents. An agent’s context window is limited and slowly gets filled as you continue working on any given task. So spawning sub-agents is a good way to create several agents with their contained context for their task, without keeping context of unnecessary information.

This package comes with its own defined sub-agents: scout, researcher, worker, oracle, evidence-auditor, reviewer, and delegate. They cover a wide variety of different use cases you would need with sub-agents, but just in case you need more, you can also make your own custom agent. You can just tell the agent how you want to work the sub-agents, and it should work.

To install the package, run:

pi install npm:pi-subagents

Pi Lens

This plugin allows our agent to see any errors, warnings, or other diagnostics within our codebase—similar to how a code editor would highlight an error in red.

You shouldn’t need to set up anything anymore to get this working.

To install the package, run:

pi install npm:pi-lens

Todo

Add a TODO that shows the progress of the agent while it works on its goal. This should give you an indicator that shows what the agent is currently working on, what it’s completed, and what it needs to work on next. Claude Code used to use this concept, but apparently, they've done this less nowadays. So feel free to skip this plugin if you don't find it useful.

This package should work whenever you give the agent any task that’s big enough. But you can also tell the agent to do a TODO list.

Install it with:

pi install npm:@juicesharp/rpiv-todo

Planning

Let your agent create a plan to implement whenever you choose. You can choose to implement the plan after it’s created, or later. This is great for thinking through the implementation of a feature without building anything yet, and it also prevents the agent from creating, editing, or destroying any files.

Use the /plan command to start a new plan.

To install, run:

pi install npm:@narumitw/pi-plan-mode

System prompt

By default, Pi’s system prompt is simple—this is by design. The agent is built to be minimalist, like a canvas we can make our own. The system prompt only tells the agent how to use tools, what its role is, and where to find its own documentation. This works perfectly fine by default, but enterprise coding agents often have much more complex system prompts to guide the agent more precisely towards the desired behavior. We should tweak the system prompt so that it behaves with more guidance. But how should we do that?

Our problems

Normally, I would use Claude Code as a guideline for our system prompt. It would be nice if we could copy it one-to-one, but unfortunately, it won’t be that easy.

Claude Code must have a robust system prompt, but Anthropic doesn’t tell us what their prompts are. They’ve never (willingly) disclosed publicly what the full system prompt for Claude Code is. So we can’t copy it easily. How do we handle this challenge?

But even worse for us—even if we could find the system prompt that Claude Code uses, we wouldn’t be able to copy it even if we wanted to. Claude Code doesn’t seem to have a single prompt that is universally used. It seems to change the prompt based on the context given to it. You can see it described in their SDK docs, where they explain that two sessions can't share cache, because the preset embeds per-session context in the system prompt:

By default, two sessions that use the claude_code preset and append text still can't share a prompt cache entry when their auto memory locations differ. The preset embeds that location in the system prompt ahead of your append text. The location defaults to an absolute path under ~/.claude/projects/ named for the repository's path on disk, so it differs across users, machines, and checkouts.

It would be nice to do something similar here with Pi too. Ideally, we would change our prompt based on the model, the task given, the project… Pi can’t do this. The community would need to build some well established packages to accomplish this. And I haven’t seen many packages that can do “context-engineering” the way that Claude Code can do. So we’re limited in being able to copy Claude Code.

How we’ll make our prompt

So I decided on the next best thing. There are plenty of open-source, enterprise AI agents—why not use them as inspiration? At first, I wanted to copy one of the system prompts from another agent, but I decided against it. Since each agent has its own purpose, goal, and style of writing code, it was difficult to choose which one was the “best”—each of them is good in some ways, and simply different in other ways.

Instead of copying one agent, I chose to read through the prompts and see what was common about all of them. I looked through Codex, Grok Build, Kimi Code, and OpenCode. I compared their system prompts and found which aspects were common among them. I built our system prompt from that. In the repo I created for this tutorial, I’ve linked all of the system prompts I took inspiration from. You’ll see that I quoted them exactly.

I would highly recommend that you read through the other system prompts and copy anything that looks like it would work well for your use case. I wrote our system prompt to be good in general use cases, but Pi is built to be customized. So you should fully customize the prompt for yourself.

Fun things I found

I found a few interesting sections while browsing through the system prompts of open source harnesses.

Codex: While searching through Codex's GPT 5.2 system prompt, I found a section in their prompt discouraging “AI slop” when creating frontend design. And to aim for designs that are “bold”. I’ve spoken with engineers who can see very noticeable differences between Codex’s and Claude Code’s design, and maybe this is why. It serves as a reminder of how important your harness can be. Very interesting!

Grok: In Grok's prompt.md, it says to never coin acronyms or technical-sounding labels, and it encourages the use of "plain language". I'm guessing this is to prevent a problem similar to the one Claude users called "Claudish", where Claude models—especially Opus 5—would speak with technical jargon that was too confusing to read.

How to set up our system prompt

We’ll now be setting up our system prompt in Pi. Pi gives us the option to overwrite the system prompt, but we won’t be doing that. Instead, we’ll add to the default prompt, so that the agent still keeps context of its tools and documentation.

We’ll be following the instructions on how to append to the system prompt, laid out to us through Pi’s thorough documentation. Create a file .pi/APPEND_SYSTEM.md (if you don’t already have one). This will add to our system prompt. It does not replace it, since, by default, the system prompt that Pi uses tells the agent how to use its tools, and what its purpose is. Next, copy the repo’s APPEND_SYSTEM.md file into yours.

To confirm that the file has been set up correctly, simply ask Pi what its instructions are; it should repeat what you put in this file. Use Pi to write some example code, to see if it's working as you like.

What Pi Isn’t good at

Although Pi is my agent of choice, there are two features in particular that Pi is lacking in compared to Claude Code. I hope that, over time, the community improves on these aspects.

Dynamic system prompts: As I’ve mentioned before, other agents dynamically change their system prompt based on the context given to them. Often, they have different prompts for different models. It seems like Claude Code can change its prompt based on the task and the codebase it’s editing—Pi, unfortunately, cannot do this. Pi allows us to add to the system prompt with an AGENTS.md file in the workspace (much like Claude Code), but we cannot dynamically add or remove from our prompt based on model, type of task, your machine, and the settings on your agent. And I have yet to find a well-established package that can do this reliably. Enterprise agents can change their context to hide defects in the model that was chosen, they can prevent token usage from ballooning, and give wider context based on the type of task given to them. This is a huge advantage to enterprise agents.
More unified supported packages: Because Pi is open source, and AI-powered coding has allowed developers to build projects much more quickly than before, I’ve seen plenty of Pi packages being built—but few that are actually maintained, tested, and used. This is a problem with all AI agents (and this problem is quickly creeping into every aspect of software engineering), but since Pi is so minimalistic, this is particularly troublesome with Pi. I don’t think there’s any “best” solution to this issue. I just hope that the community can unite more often to focus on a few good packages instead of building many different ones.

Where to go from here?

Pi is all about its freedom and customization—you should do whatever you’d like from this point on. In case you need a few suggestions, I’d suggest you continue working on your system prompt. If you looked at the system prompts from the other agents, you’ll see how much depth they go into to make them specialists in their tasks, sometimes even containing highly specific instructions on a certain type of task (tests or front-end design, for instance). I would recommend you continue to adjust your system prompt until it suits your needs.

If you’re missing any packages that would make your experience better, you should search for them on https://pi.dev/packages. Personally, I think that less is more with the agent, so I wouldn’t add more packages than you need. But experimentation can be fun, so I would recommend that you browse the packages to find anything useful.