phi: a Go coding agent with sub-agents, hashline edits and MCP meta-tools

What phi is for, and who it is not for

phi is a coding agent that runs in your terminal. The README calls it "a lean, high-performance terminal coding agent harness in Go", a sibling to Pi. The model gets four core tools (read, write, edit, bash) plus grep, find and ls, and uses them to carry out requests against your working tree.

The intended user is someone who already lives in a shell and is tired of agent harnesses that pull in a Node, Electron or Python runtime. The README states the release binary is about 15 MB, idle RSS about 21 MB for one session, and time to first frame about 31 ms, measured on a stripped release build (CGO_ENABLED=0, -ldflags="-s -w") on macOS arm64. Those are the project's own figures, not independent measurements.

It is not for people who want a graphical editor with an agent bolted on. There is no GUI in the README; the closest thing is an HTML config editor opened in your browser by phi config. It is also not a hosted service. Everything runs locally, and you supply your own model credentials.

Sub-agents, hashline edits and the permission gate

Three mechanisms separate phi from a plain chat loop.

Sub-agents spawn isolated jobs whose full run appears in the TUI or job logs. The stated benefit is context hygiene: the parent conversation does not absorb every turn of the child job. That is a real architectural choice, and it means the parent's view of a sub-agent is a summary rather than the raw transcript.

Hashline edits change how the model modifies files. Instead of rewriting whole files, the model points at a whole-file anchor in the form @file path#TAG plus per-line anchors in the form LINE#HASH. The README says stale tags or hashes are rejected, which is the interesting part: the edit fails rather than applying against a file that moved underneath it. The README credits oh-my-pi for the same idea. The trade-off is that the model must produce correct anchors, and a rejected edit costs a round trip.

The permission gate sits in front of destructive tools with Gate and Ask modes. The README is blunt about why: "safety is not optional when an agent can touch your tree". MCP calls go through the same Gate, Ask and Hooks path as built-in tools, which matters because otherwise a remote tool would be a way around the gate.

MCP without filling the prompt with tool schemas

The usual cost of MCP is prompt bloat. Every server contributes its tool schemas to the model's context, whether or not the agent will ever call them.

phi takes a different route. The README states that MCP tool schemas never enter the model prompt. The system prompt lists server names only, described as being like the Skills catalog, and the agent discovers and calls tools on demand through three meta-tools: mcp_list, mcp_inspect and mcp_call. You can configure as many servers as you want without a proportional rise in system prompt size.

The cost is an extra hop. The model has to list, then inspect, then call, rather than emitting a tool call directly. For a server the agent uses constantly, that is overhead on every invocation. For a long tail of servers touched once a session, it is a clear win. The README does not describe a way to promote a hot MCP tool into the always-visible set, so the choice is global rather than per-server.

Installing phi and running a first session

On macOS and Linux the README gives a one-line installer. It fetches the latest release and runs it through bash.

curl -fsSL https://raw.githubusercontent.com/pulseaiclub/phi/main/scripts/install.sh | bash

Windows users get a PowerShell equivalent, documented for PowerShell 5.1 and above.

irm https://raw.githubusercontent.com/pulseaiclub/phi/main/scripts/install.ps1 | iex

If you prefer to build from source, the README requires Go 1.26.3 or later and points at go.mod. The Makefile builds with CGO disabled and stripped symbols by default.

make build          # produces ./phi
make install        # build and install into $GOBIN

A first launch needs a model. The config editor creates the ~/.phi layout and writes ~/.phi/config.yaml.

phi config

For a one-off run you can skip the file and export environment variables instead, then start the TUI with phi.

export PHI_MODEL=gpt-4o
export PHI_API_KEY=sk-...
phi

On first start phi creates ~/.phi/{bin,skills,hooks,session}. The README notes that the search tools fd and rg download into ~/.phi/bin in the background when they are missing, so grep and find may not be usable the instant the TUI appears.

Configuring models explicitly, and why there is no guessing

phi reads ~/.phi/config.yaml, with environment variables overriding it for one-off runs. The README's example shows an api field that must be set to OpenAI, OpenAIResponses, Anthropic or Gemini; leaving it empty falls back to OpenAI-compatible. The README states plainly that Anthropic requires the api field because there is no name or URL guessing.

models:
  - name: gpt-4o
    api: OpenAI
    api_key: sk-...
    base_url: https://api.openai.com/v1
    context_window: 128000
    default: true
  - name: claude-sonnet-4-20250514
    api: Anthropic
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    context_window: 200000

DeepSeek and Gemini have built-in presets that fill in base_url, context and thinking settings, so those entries need only a name and key. There is also a think_level key with values including off, minimal, low, medium and high.

Explicit configuration is the right default for a tool that spends your money, but it does mean a mistyped api value is a configuration error rather than something the harness papers over. The default model is the one marked default: true, and the first entry wins if no entry is marked.

Extensions, and the limits the README leaves open

Extensions are native binaries, written in Go or Rust, that speak the PXB binary protocol over stdin/stdout. The repository ships author SDKs at ext/go and ext/rust. They can add LLM tools, slash commands, event intercepts and confirm dialogs. The README notes there is no reflection, with JSON confined to the SDK edges via serde_json.

That design keeps the hot path binary and avoids a runtime, but it raises the bar for writing an extension: you need a Go or Rust toolchain and a build step, not a script dropped into a folder. The Makefile has separate targets for the Rust SDK, test-rust and check-rust, which suggests the two SDKs are maintained in parallel rather than one being a wrapper around the other. go.mod pins github.com/pulseaiclub/phi/ext/go at v0.24.0 with a replace directive pointing at ./ext/go, so a source build uses the in-tree SDK while a module consumer gets the tagged version. Those can drift.

The README does not document rollback for an edit the agent has already applied, and it does not describe what happens to a sub-agent job if the parent session exits. Both are worth confirming against the source before you rely on phi for work you cannot redo.

How phi differs from Claude Code and Codex CLI

The obvious alternatives are Claude Code and Codex CLI, both of which the repository's topics list alongside phi. The difference is not the task, it is the packaging and the extension surface.

Claude Code and Codex CLI are distributed through their own vendor channels and tie you to that vendor's models and tooling. phi is a single Go binary with six direct module dependencies, per go.mod, and it talks to OpenAI-compatible, Anthropic or Gemini endpoints through the api field. If your constraint is "must run on this machine with no Node runtime and must point at whichever endpoint I choose", that is the case for phi.

If your constraint is the opposite, and you want the vendor to own the update path, the model integration and the plugin catalogue, a harness you build and patch yourself is a liability rather than an asset. The same applies to teams that need a reviewed, versioned plugin marketplace: phi's extensions are native binaries you compile from the Go or Rust SDKs in this repository.

Editorial conclusion

phi suits engineers already comfortable in a terminal who want a small Go binary, a permission gate in front of destructive tools, and MCP servers that do not inflate the system prompt. It is the wrong choice if you need a GUI, a Node or Python extension ecosystem, or a documented rollback story, because the README does not describe one. Before adopting it, check the last push date, read doc/models.md for the api field values, and confirm that the extension protocol you plan to target (Go or Rust) matches the SDK version pinned in go.mod.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. pulseaiclub/phi on GitHub
4. README
5. Releases