zopu-code/.agents/skills/ai-agent-workspace/reference/agent-os/agents/pi.md

Pi

Source: src/content/docs/agent-os/agents/pi.mdx Canonical URL: https://rivet.dev/docs/agent-os/agents/pi Description: Run the Pi coding agent inside a VM with extensions and custom configuration.

---

Quick start

import { agentOs } from "rivetkit/agent-os";
import { setup } from "rivetkit";
import common from "@rivet-dev/agent-os-common";
import pi from "@rivet-dev/agent-os-pi";

const vm = agentOs({
  options: { software: [common, pi] },
});

export const registry = setup({ use: { vm } });
registry.start();

import { createClient } from "rivetkit/client";
import type { registry } from "./server";

const client = createClient<typeof registry>("http://localhost:6420");
const agent = client.vm.getOrCreate(["my-agent"]);

const session = await agent.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const { text } = await agent.sendPrompt(
  session.sessionId,
  "What files are in the current directory?",
);
console.log(text);

Read Sessions first for session options, streaming events, prompts, and lifecycle management.

Extensions

Pi supports extensions that let you register custom tools, modify the system prompt, and hook into agent lifecycle events. Write a .js file into the VM's extensions directory before creating a session and Pi discovers it automatically.

Pi scans two directories for .js extension files:

Directory	Scope
~/.pi/agent/extensions/	Global — applies to all Pi sessions
<cwd>/.pi/extensions/	Project — applies only when cwd matches

const extensionCode = `
module.exports = function(pi) {
  // Modify the system prompt before each agent turn
  pi.on("before_agent_start", async (event) => {
    return {
      systemPrompt: event.systemPrompt +
        "\\n\\nAlways respond in formal English."
    };
  });
};
`;

// Write the extension before creating the session
await vm.mkdir("/home/user/.pi/agent/extensions", { recursive: true });
await vm.writeFile("/home/user/.pi/agent/extensions/formal.js", extensionCode);

// Pi discovers the extension automatically
const { sessionId } = await vm.createSession("pi", {
  env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
});

See the Pi extension documentation for the full extension API.

Source doc path: /docs/agent-os/agents/pi