Why I switched to Pi...

Introduction to Pi Agent and Sponsorship00:00

Thanks HubSpot for sponsoring this video. If you're into AI agents, you've probably heard about this Pi agent quite a lot recently. Most people know Pi agent because it was what powering Open Claw. The goal is to give a breakdown of what's special about Pi agent, why it is one of the best option for building agent systems, and how to use Pi to build some agentic system like Post AI from scratch, which is an agent designed to launch and run a business.

Before diving into Pi, many users are already using coding agents like Cloud Code or Codec everyday. However, there's probably a 10 or even 100X difference between someone who just opens terminal, sends a prompt, and hopes for the best versus someone who fully utilizes every aspect of what this modern harness provides. Things like what type of Cloud or MD or agent.md actually works, how to structure code base that is agent ready, what hooks are set up, how to keep long running work on track with task state, and how to run more post sessions without creating a complete mess.

Cloud Code Playbook and HubSpot Sponsorship00:31

If you want to be on the right side of the gap, then the free Cloud Code Playbook created with HubSpot will get you there. This is a playbook that covers prompting patterns, how to set up Cloud or MD and project context, which hooks and guardrails to use, and how to manage task state for longer work. The favorite part is probably the parallel sessions setup that enables running not just one or two sessions, but 10 to 15 different agent sessions safely at the same time.

Although it is called the Cloud Code Playbook, the principles actually apply to Pi as well. Because for every Cloud Code feature, there's almost an equivalent package that can be plugged into the Pi agent. Most of the principles here are harness agnostic, which means no matter which agent is used, the approach can be adopted. The link is in the description below to download for free.

Understanding Pi Agent as a Coding Agent01:31

Fundamentally, Pi agent is a coding agent. When people ask whether Cloud Code is better or Codec is better, the answer for the past few weeks is that they are the same. There's no real difference between those coding agents anymore. However, the question is why Open Claw chose Pi Agent as the base to build upon.

CloudCode, CodeX, OpenCode all have their own SDK and CLI that allow building new agent systems by wrapping them. The core difference is that all the other coding agents harness, even though they're really powerful, can't really modify or change how the harness inside it works. Even CloudCode and CodeX are becoming increasingly similar to each other, but each one still has their own unique features. Like CloudCode has dynamic workflow, but if you're a user of CodeX, you can't just tell CodeX to implement this dynamic workflow as part of your harness, and vice versa.

Limitations of Existing Coding Agent Harnesses02:00

Even though other agents have tried to open up more customizability by exposing hook systems to the user, hooks normally allow defining some programmatic behavior when certain things happen, like when a session starts or before the agent tries to call a tool. Some sort of harness modifications can be achieved by doing things like every time CloudCode tries to call a tool, it automatically checks permission rules that are written and then returns back true or false based on permission rules that are wanted. It's pretty powerful, but still a bit limited. Looking at GitHub issues, there are a lot more scenarios of hooks that users want to modify but couldn't.

Pi Agent's Design Philosophy and Extension System03:02

This is where Pi Agent really shines. The whole design philosophy of Pi Agent is that harness should actually adapt to the user rather than the other way around. At default, Pi comes with a minimum version of coding agent. It only has four critical tools: run bash command, write, read, and edit files. There's no sub agents, no agent teams, and doesn't even have MCP comes with it. It's very bare minimum.

Meanwhile, it can be easily extended with any other features wanted. They have this concept called extension. Users and agents can just write new extension files to extend the Pi coding harness. They expose a whole bunch of things to allow modifications across tools, contexts, hooks, session management, command UI, almost everything that can be thought of. New tools, command shortcut providers, large language model providers can be added, and almost every single hook that will ever be needed is exposed. Programmatic behavior can be written to change and improve the harness. The UI itself is even exposed as well.

Real-time Extension Capabilities and Package Catalog04:00

For example, the Pi Agent UI can be customized to whatever is wanted, like this random character. The cool thing is that these extensions can be written by humans or by the agent itself. Pi Agent has its knowledge baking already and has full awareness of what kind of extension is already loaded and how to write the extension. It can be modified on the fly. For example, it can be told "Hey, I want to see the weather info in the prompt input. Help me customize your UI." It will automatically read the extension doc, then write a new extension for the weather widget. Once it's done, {slash} reload can be done and it will immediately reload the latest version of the harness that it just created with those extensions. Now the weather information is showing up just above the prompt input.

This type of UI customization is just really a small part of all the possibilities. Almost any part of the harness can be updated on the fly. There's a Pi Agent package catalog where extensions built by others can be installed. Even though default Pi Agent doesn't have any of those features, almost every popular Cloud Code Codex feature is already implemented by someone that can be plugged into the Pi Agent, like the Go feature, the MCP adapter, the Chrome browser access, the ask user question tool, sub agents, plan mode, and even dynamic workflow and computer use.

Dynamic Workflow and Feature Parity05:01

If dynamic workflow needs to be enabled, the package of dynamic workflow can simply be copied, the command can be run, then reload. Now a prompt including keywords like workflow can be given, then it works almost like Cloud Code's dynamic workflow feature. It will trigger workflow, and {slash} workflow can also be done, which will pop up the workflow UI, and a very similar, almost identical experience from Cloud Code is obtained. There are even packages that will just turn Pi Agent into Cloud Code or Codex. The packages have all the special tooling those other harnesses have, so they can be installed and used. There are even extensions that allow playing DOM while the agent is running. Some of the extensions might not be well-built, but technically the agent can be asked to update and build for the user.

Pi Hyper Package and Token Optimization06:01

With this flexibility, some really interesting things can already be seen that are only possible to be built with Pi. For example, this one package called Pi hyper. What it does is that it will capture every tool call hook for things like bash command to actually make sure it pre-processes the bash command result and only returns relevant and minimum information back to the agent. For example, previously, if agent is running Git log to see what are recent commits, the command will include a lot of information for each commit like hash, author, date, body, and diff blocks. But with this package, it will actually clean things up to show only what matters. And just by doing this, it can probably reduce 96% of those type of commits. And in some other testing commits, it will cut token by like 80 to even 90%.

This is a good example where things like that is just difficult to implement with Cloud Code or Codex because their pre-tool use hook only allows appending new information to the tool call rather than directly modifying the tool call result. This rich extension system is the core that makes Pi agent super useful and this is exactly how Open Claw started.

Open Claw's Architecture and Extension Building06:30

First what they were building is mainly the gateway to connect with app Slack and the web interface while using the Pi agent as the main agent runtime. The agent loops, large language model OS, and the session management can be utilized, but also extended with MCP, memory sub agent, ACP, and many other things. Those types of customizability would be otherwise very difficult to achieve if Open Claw were using Cloud Code SDK or Codex CLI.

It's actually pretty easy to build those extensions. To build an extension, a .pi folder can be created in any project folder or in the root and then an extensions folder can be added inside it. Here are a few examples.

Git Context Extension Example07:31

Let's say the agent's context needs to always be aware of the current Git repo like which branch it is on, what are the available work trees, un-staged changes, and recent commits. An extension can be created like this, which is in TypeScript, and adding a Git function which will run the Git command to get all those Git related information back, extract and generate a Git summary. Then just simply do pi.on_before_agent_start and modify the system prompt, append additional Git context after the predefined system prompt. This is as simple as it gets. Once this extension file is put here, the next time the Pi agent is loaded, it will automatically have those contexts. It can be simply asked "What's the Git information here? Use no tools to answer me." And it will return back the information.

Custom Tool Creation and Clipboard Example08:01

Meanwhile, custom tools can also be easily added. Like, what if the Pi agent needs to be able to read what's in the clipboard? This can be done simply with pi.register_tool, giving it a name, label, description, and param, then defining the actual function here. With this, if the previous Git context extension file is copied, and it is asked "What's in my clipboard?" It will use the tool that was written to get clipboard information.

Permission Gate Extension with Small Model08:31

Something more interesting can even be built, like this permission gate. The idea is that what if this agent is to be used by a team, where each one might have different permission access to different levels of information? Instead of message sent directly to agent, or let the agent decide whether the user has right permission, what if a permission check is added using a cheap and fast small model? If it's all good, then continue with agent as normal. But if it is some dangerous information, the session can be stopped right away.

Here, another extension is written. Two different packages are being used, which will be dove into a bit deeper. One is a Pi coding agent that allows writing extension API, but also this Pi AI package, which is some package from Pi agent that allows large language model calls with any model very easily. A small gate model is defined to use Haiku and output decision whether it's allowed or denied, plus a reasoning. Then this is packaged as a small decide tool, the system prompt, as well as the user message, which loads up both the policy, which is a permission.md file that users can define on the root, plus the user request. The function provided by the Pi AI package is used to direct call the large language model and output result.

All that needs to be done is just when the session starts, the policy information is loaded up in the prompt. Then after every time a user sends a message, a message is shown on the UI saying permission checking, waiting for the large language model result. If it is denied, then on the UI this block information is shown and skips agent entirely. Otherwise, continue like normal.

Permission Testing and Pi Package Ecosystem10:01

To test it, a permission.md file can be defined to define specific permission. Like here it said only Jason can get revenue data. So if going to Pi agent, asking what's the revenue for June, it will trigger permission and show back this information that is blocked. That you don't have permission to access revenue information. This is one example of how Pi agent's harness can be updated by writing those extensions. Most of the time actually don't need to learn building those extensions yourself, because the Pi agent can be talked to and it will self-evolve.

However, the real power of Pi, from this point of view, is actually not just using it as a coding agent, but actually building on top of Pi agent to power AI products. If looking at Pi agent repo, it actually comes with five different packages.

Pi Agent Package Architecture10:31

The first one is this AI package. This is almost like a Vercel AI SDK that allows calling different large language models. It comes with all the OAuth function to allow users to connect Cloud Code subscription, Code Act subscription. This can actually be used as standalone function to just do large language model calls in the application being built.

The second package is this agent package. This is basically the agent loop. This can be considered almost like a Vercel AI SDK stream text function that has this small agent loop built in.

The third one is this coding agent. The coding agent can use agent core loop as well as AI package, but comes with essential tooling like read, write, add, and bash, as well as session management, compassionate context window, the extension system, as well as SDK. This package can almost be considered as equivalent to the Cloud Code agent SDK, but it is fully customizable and can connect to any model wanted.

In the end it also comes with this TUI package that wraps the coding agent in this terminal UI. And also an up trader package. This up trader package allows building like scheduled jobs or delegate tasks to different Pi agent processes. This has been more experimental. Based on the type of product being built, the Pi agent's ecosystem can be utilized to scaffold the agent products.

Building Post AI with Pi SDK12:01

This coding agent SDK was utilized to build a product like Posia, which is a times agent that can launch and run business to showcase the real power. If trying to build a local agent, which means the agent system that lives on user's own computer, then this package basically gives most of the stuff needed. Functionality can be easily extended by building extension system, custom UI, and task triggers.

One good example is this all my Pi coding agent. This is a coding agent that is built on top of Pi package. But it comes with a lot of new tools that brings performance closer to Cloud Code Codex. It comes with editor type of user interface inside terminal. It even has features that allow publishing a specific conversation session had with someone else. It has a QR code that people can scan or a URL that can be shared with others. Very sophisticated local agent products can be built on top of Pi agent.

Web-Hosted Agent Development Considerations13:01

Meanwhile, Pi agent package can also be used to build web hosted agent products like this Posia replica. But there are some nuances that need to be handled because the Pi e-coding agent SDK at default is designed quite tied to the local file system. When having this web deployed agent, which means agent run actually lives on shared backing infrastructure, but when trying to write file, run bash command, then each user has their own sandbox. With this type structure, some modifications will need to be made.

Instead of using Pi coding agent default session manager system, which is directly tied to the general file on the computer, session information probably needs to be stored in the DB and manage compassion yourself. Also for the default bash added read write tools, a layer probably needs to be wrapped so that operations will be done in the sandbox that the user is owning. But it is the same situation that needs to be handled even though Cloud Code agent SDK is being used.

Resource Loader and Custom Extensions for Web Deployment14:01

With this, a web application like this can also be built, which is a chat agent. Users can chat to it. To implement such experience, the Pi coding agent package is still pretty much being used. But this time the default resource loader is used. This is how additional extension skills can be passed to the coding agent. For example, here an extension is defined for guardrail that will block by running certain bash commands. Also a tool is defined to get MRR with some mock result. Then this resource loader is defined. The directory the agent should be working in can be passed and the directory where agent should load extension file like OS key. Whether the agent should just load up extension skills from the door pi folder can also be defined. Customized extensions can also be passed. Like here, the guardrail's extension is being passed that was defined in line here, as well as additional skills. This will allow customizing what type of skills each agent session should have access to.

Then this create agent session function is used to pass the custom tools as well as a resource loader. The rest will be similar. Based on the type of events, different information can be presented on the UI. This is how a wrong Pi package can be built. The same Pi SDK was used to build a replica version of Post here, which is a hosted agent system that can launch and run company autonomously. It is using Pi's coding agent SDK as agent runtime. Breaking down into 11 different agents with orchestrator that's built around task entity and persist the state and context as well as tools proxy.

More details step-by-step tutorial of how the system was built from scratch will be shared in a builder club. If interested, join there. Meanwhile, some of the extensions built or some favorite Pi extensions will be added into the curious skill folder. They can be given to Pi agent and have it set up.