Pi in AI Maestro: what works, what we fixed, and what it is not

AI Maestro · October 28, 2026

Pi is a small terminal coding agent (MIT license, npm package @earendil-works/pi-coding-agent). It has no model of its own: you point it at one of many providers. AI Maestro could already start it in a terminal. This post is about what happens after that: whether an agent running Pi can take part in a fleet the way a Claude Code agent does. We tested it on a real cloud VM with Gemini on Google Vertex AI, found several problems, fixed what we could, and wrote down what is still missing.

How sure we are. Everything below was run, not read: Pi 1.4.0 on Ubuntu 24.04, Node 24.22.1, AI Maestro 0.106.x, Gemini 3.5 Flash-Lite and 3.8 Flash through Pi’s built-in google-vertex provider. We did not test long sessions, context compaction, models other than Gemini, or Windows. Where we only read documentation, we say so.

What works today

Launch. Choose Pi in the Wake dialog or set the agent’s program to pi, pi-agent or pi-coding-agent. The agent CLI now accepts those names too (plugin 1.18.4); before that, aimaestro-agent.sh create --program pi was rejected.
Message delivery that is checked. A message sent to a Pi agent goes into its input and AI Maestro checks that it was submitted, the same readback check used for the other programs. A message with no model behind it is reported as not delivered instead of claimed.
Chat history. Pi writes its sessions as JSONL files. AI Maestro reads user messages, tool calls with their results, and replies, and shows them in the chat view. We confirmed this on a live agent with a real model, not only on fixtures.
Working / idle status. The status feed reads Pi’s session file. Pi writes an entry only when a step finishes, and a Pi that crashes mid-turn would look “working” forever, so a “working” file that has not changed for 10 minutes now reads as unknown.
Messaging tools. Pi does not come with AI Maestro’s messaging skill, and an agent that does not know about it answers in its own terminal, where nobody reads it. We ship a small Pi extension with four tools (amp_inbox, amp_read, amp_reply, amp_send) that call the AMP scripts with an argument list and stdin, never a shell string, plus a managed block in ~/.pi/agent/AGENTS.md that says only an AMP reply reaches the person.
A restricted tool set. A “messaging” profile gives an agent read plus the four AMP tools and the MCP tools you list, with no shell, no write and no edit.
An installer. scripts/install-pi.sh installs Pi with its own Node and a small wrapper, so a tmux pane finds a working pi without changing the host’s default Node. --vertex <project> sets it up for Gemini on Vertex AI with the VM’s own Google login.

What we found, and what we did about it

Pi needs a newer Node than many hosts have. Pi 1.x uses zlib.createZstdDecompress, which exists from Node 22.15 (and 23.8, and 24). Pi declares >=22.19, so Node 23.5 passes its check and then crashes. AI Maestro now reads that crash from the terminal and says “Pi needs a newer Node” with the fix, instead of reporting a mystery.
Pi’s Vertex AI credential check ignores cloud-VM credentials. On a Google Compute Engine VM the identity comes from the metadata server, with no gcloud login file. Pi’s readiness check only looks for such a file or a key, so it answered “No API key found” before making any request. Pi’s providers documentation says Vertex AI can use ambient cloud credentials, but on our VM it did not. Pi’s changelog describes a gcp-vertex-credentials value as an Application Default Credentials marker; putting it in models.json made Pi use Google’s own auth library, which did work on the VM. install-pi.sh --vertex writes it. We filed an issue with the Pi project (earendil-works/pi#11548). It was closed automatically as a new-contributor issue; the maintainers say they review such issues daily, and at the time of writing it has not been reopened.
Gemini 3 needs its thought signatures. Through an OpenAI-compatible endpoint, every tool call failed with INVALID_ARGUMENT, because Gemini 3 wants a “thought signature” returned with each tool call and that connection drops it. Pi’s native google-vertex provider handles it. Use the native provider.
Tool restrictions are not a sandbox. Pi’s security documentation says that Pi does not ask for approval before every tool call, that prompt injection can steer the model, and that safety comes from limiting what Pi can reach; it has no built-in sandbox. A --tools allow-list limits what the model can call, and we treat it as a way to reduce accidents, not as a boundary. Keep credentials off the machine and put the dangerous capability behind a service, as we did for database access.

How it did

We ran a set of support questions in Spanish through Pi with two Gemini models, using the messaging tools and a read-only data connector, with each question arriving as a Google Chat event from an untrusted user. The agents answered through the messaging layer, and when we asked them to run a command or change a record, they did not. This was a small functional test, not a benchmark, and we publish no performance figures.

What Pi is not

It does not ask for approval before every tool call, so there are no “needs you” cards for Pi agents.
It has no sandbox.
It is not tested here for long sessions, compaction, local models, or Windows.

Try it

scripts/install-pi.sh --vertex <your-project>      # Pi + Gemini on Vertex AI, no API key
aimaestro-agent.sh create my-agent --dir ~/agents/my-agent --program pi

The details, including the environment each check ran in, are in docs/AGENT-PROGRAMS.md and backlog item F036 in the repository.

Claude is a trademark of Anthropic. Gemini, Google Cloud, Vertex AI, Google Chat and Pub/Sub are trademarks of Google LLC. Pi is published by earendil-works under the MIT license. AI Maestro is not affiliated with or endorsed by them.