phi

English | 中文

A minimal terminal coding agent harness in Go — a sibling to Pi.

• Sub-agents — spawn isolated jobs and watch the full run unfold in the TUI / job logs, without stuffing every turn into the parent context

• Hashline edits — edit by whole-file @file path#TAG plus line LINE#HASH anchors (same idea as oh-my-pi): the model points at anchors instead of rewriting whole files; stale tags/hashes are rejected so over-edits and silent corruption stop here

• Permission gate — Gate / Ask before destructive tools fire; safety is not optional when an agent can touch your tree

• MCP without context death — configure as many MCP servers as you want; their tool schemas never enter the model prompt. The system prompt lists server names only (like the Skills catalog); the agent uses three meta-tools (mcp_list / mcp_inspect / mcp_call) to discover and call on demand. Same Gate / Ask / Hooks path as built-in tools. See MCP

• Any model — OpenAI-compatible or Anthropic, no vendor lock-in

• Quick start

• Footprint

• Configuration

• Interactive mode

• Commands

• Sessions

• Headless mode

• Skills

• Permissions

• Hooks

• MCP

• Tools

• Project layout

Quick start

Install the latest release (macOS / Linux):

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

Windows (PowerShell 5.1+):

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

First launch needs a model. Open the config editor (creates ~/.phi layout and writes ~/.phi/config.yaml):

phi config

Or set env vars for a one-off run:

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

Then start the TUI:

phi

Or build from source (Go 1.26.3+, see go.mod):

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

On first start, phi automatically creates ~/.phi/{bin,skills,hooks,session}. Search tools (fd, rg) download into ~/.phi/bin in the background when missing.

The TUI gives the model four core tools — read, write, edit, and bash — plus grep, find, and ls. The model uses these to fulfill your requests. External HTTP fetch is available via MCP when configured.

Footprint

phi aims to stay cheap to run and cheap to hack on. Numbers below are for a stripped release build (CGO_ENABLED=0, -ldflags="-s -w"), measured on macOS arm64 unless noted.

Metric phi

Release binary ~12 MB

Idle RSS (1 session) ~21 MB

10 idle sessions (total RSS) ~196 MB (~20 MB each)

Time to first frame ~40 ms (27–65 ms)

Cold go build (empty GOCACHE) ~5.5 s

Warm rebuild ~0.7 s

Go source (excl. tests) ~22k LOC / 107 files

Go packages 32

Direct module deps 6 (15 modules total)

Linked runtimes system libs only (no Node / Electron / Python)

Configuration

phi reads ~/.phi/config.yaml (standard YAML). Environment variables override it for one-off runs. phi config opens an HTML editor for the same file in your browser.

# ~/.phi/config.yaml
models:
  - name: gpt-4o            # model name; "claude-*" routes to the Anthropic API
    api_key: sk-...         # or set PHI_API_KEY
    base_url: https://api.openai.com/v1   # default; PHI_BASE_URL overrides
    context_window: 128000  # optional
    default: true           # the model used at startup; first entry wins if absent
  - name: claude-sonnet-4-20250514   # extra models; switchable at runtime
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    context_window: 200000

skill_path: ~/.phi/skills # where SKILL.md files are loaded from

agents:
  enabled: true           # default; set false to disable agent_* sub-agent tools

permissions:
  mode: interactive       # interactive | readonly | autopilot | headless-strict
  bash:
    default: ask          # ask | allow | deny
    allow:
      - "go test ./..."
    deny:
      - "rm -rf *"

Recommended model: DeepSeek Flash

phi + DeepSeek Flash — the best pairing: grounded, low hallucination, cache hit rates near 100%.

Measured data:

39 LLM rounds, same session — prompt 16k→40k, hit rate 95–100% (avg 98.7%).

Round Prompt tokens Cached tokens Cache hit

1 16,176 15,872 98.1%

10 20,163 20,096 99.7%

20 27,604 26,624 96.4%

30 35,245 35,072 99.5%

39 39,794 39,552 99.4%

xychart-beta
    title "Cache hit % (39 rounds)"
    x-axis [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39]
    y-axis "Hit %" 95 --> 100
    line [98.1, 98.8, 97.5, 98.1, 98.1, 98.8, 99.1, 99.9, 98.7, 99.7, 99.5, 99.5, 96.3, 99.4, 97.0, 99.7, 99.9, 99.3, 98.3, 96.4, 98.9, 98.7, 97.2, 99.8, 95.0, 99.7, 99.2, 98.9, 99.3, 99.5, 99.5, 99.4, 99.2, 98.6, 99.4, 99.6, 100.0, 97.8, 99.4]

Environment overrides:

Variable Overrides

PHI_API_KEY models[].api_key (default model)

PHI_MODEL models[].name (default model)

PHI_BASE_URL models[].base_url (default model)

PHI_SKILL_PATH skill_path

Provider routing: a base URL containing anthropic or a model name starting with claude uses the Anthropic Messages API; everything else uses the OpenAI-compatible /chat/completions path.

Workspace layout

~/.phi/
├── config.yaml   # global configuration
├── bin/          # downloaded search tools (fd, ripgrep)
├── skills/       # SKILL.md skill directories
├── hooks/        # plugin.json + hook scripts
├── jobs/         # sub-agent job artifacts (meta, logs, result.md)
└── session/      # persisted sessions, one dir per working directory
    └── <encoded-cwd>/

Interactive mode

phi (or phi tui) starts the TUI: a chat transcript on top, an editor at the bottom, and a footer with the current activity. When a newer release is available, the footer shows a hint like 0.2.0 available · phi update.

Assistant output is rendered as Markdown (CommonMark/GFM): headings, emphasis, strikethrough, links, blockquotes, lists, task checkboxes, and tables are styled with the active theme; fenced code blocks get a muted language caption and per-language syntax highlighting. Structural markers (#, ```, *) are stripped.

The editor supports:

• @ — fuzzy file mention picker (type @ and start typing a path)

• / — slash command picker (/sessions, /resume, /clear)

• !command — run a shell command locally and stream its output into the transcript (see Commands)

• Ctrl+K — command palette: settings → model / theme / permissions / agents, skills, hooks

Keyboard shortcuts

Key Action

Ctrl+C Quit phi

Esc Cancel the running agent / close pickers

Ctrl+K Toggle the command palette

Ctrl+Shift+C Copy the selected transcript text

Themes: Dark, Darcula, Pink, and Terminal (default), switchable from the palette under settings → theme.

Commands

Command Description

phi / phi tui Start the interactive TUI

phi run -p "…" Run one agent loop headlessly (see below)

phi update Download and install the latest GitHub release

phi update --check Query the latest release without installing

phi sessions list List persisted sessions for this directory

/sessions List sessions for this directory (TUI)

/resume <id> Resume a session by id or unique prefix (TUI)

/clear Start a fresh empty session (TUI)

!command Run a shell command locally, stream output into the transcript; Esc cancels it

In the TUI, !command runs locally via bash -c — outside the agent loop. It doesn't count toward agent busy state, and the running command can be cancelled with Esc without touching an in-flight agent turn.

Sessions

Sessions persist automatically per working directory under ~/.phi/session/<encoded-cwd>/ as JSONL trajectories.

• phi sessions list — list session id, mtime, and preview for the current directory

• /sessions in the TUI — same, in-app

• /resume <id> — continue a session (id or uniqu