pi-callflow

On-demand call-structure viewer for pi. Ask the agent to show how a request flows through the code — e.g. "show the call structure starting from login" — and pi-callflow renders a live Mermaid sequence/flowchart in a native Glimpse window, with every step grounded to a real file:line.

Built for onboarding onto large codebases (e.g. a 3.5k-file Java monolith) where reading call flows as terminal text is slow.

How it works

1. You ask pi to show a call flow.
2. pi inspects the actual code, then calls the render_call_diagram tool.
3. A persistent Glimpse window shows the result in tabs — a Sequence tab (default, call ordering) and a Flowchart tab (branch logic, shown when provided) — plus a step panel (from → to : call with file:line).
4. Click a step to open it in your editor.

Each diagram sits on a zoom/pan stage: wheel zooms at the cursor, drag to pan, +/−/⌗ buttons and double-click to fit — handy when the flow gets large.

The tool schema requires a file:line for every step (grounding-lite), so the diagram stays tied to real code instead of being a plausible-looking hallucination.

Usage

One package, two ways to run it. Pick whichever agent you use.

Option A — with pi (first-class)

Install it as a pi package — this registers the /callflow command and the extension in every project (prebuilt viewer ships in the package, no local build):

pi install npm:pi-callflow

pi install -l npm:pi-callflow      # project-only (writes .pi/settings.json, shareable)
pi -e npm:pi-callflow              # one-off for a single session, no install
pi update npm:pi-callflow          # update to the latest published version
pi update --all                    # update pi + all installed packages
pi remove npm:pi-callflow          # uninstall

Then open pi in your project and ask for a flow, either with the /callflow command or in plain language:

cd ~/dev/your-project && pi

/callflow "show the call flow from the /login endpoint"
#  → agent analyzes the code, then the window opens with the result.

/callflow                      # (no arg) just open an empty viewer

# plain language works too — no slash command needed:
show the call flow from the /login endpoint

In pi the window opens when the agent finishes the turn. If the agent calls the tool, the window opens at the end of the turn.

Option B — with Claude Code / Codex (MCP)

The same viewer is a local stdio MCP server, so teammates on Claude Code or Codex get the identical render_call_diagram tool and native window. Install once — this puts pi-callflow-mcp on your PATH (no clone, no build, no absolute paths):

npm i -g pi-callflow

Or skip the install entirely and let the agent run it via npx — this auto-updates, since @latest re-fetches the newest published version every time the MCP server launches. Note the npx target is the package name pi-callflow (not the bin name pi-callflow-mcp):

npx -y pi-callflow@latest

Claude Code — one command (auto-updating):

claude mcp add callflow -- npx -y pi-callflow@latest

Codex — add to ~/.codex/config.toml (auto-updating):

[mcp_servers.callflow]
command = "npx"
args = ["-y", "pi-callflow@latest"]

(Prefer a pinned global binary instead? Run npm i -g pi-callflow, then use command = "pi-callflow-mcp" — that bin name is only valid on your PATH after a global install, not as an npx target. On startup the server checks the registry once and logs a one-line notice to stderr when a newer version is out; set CALLFLOW_NO_UPDATE_CHECK=1 to silence it.)

That's it. Then ask the agent in plain language:

show the call flow from the /login endpoint

The agent analyzes the code, calls the render_call_diagram tool, and the window opens as soon as the tool is called.

If you cloned the repo instead of installing globally (git clone + npm install builds dist/mcp-server.mjs), point at it directly:

claude mcp add callflow -- node /Users/you/dev/pi-callflow/dist/mcp-server.mjs

# ~/.codex/config.toml
[mcp_servers.callflow]
command = "node"
args = ["/Users/you/dev/pi-callflow/dist/mcp-server.mjs"]

Set the repo root so file:line clicks resolve correctly (defaults to the server's working directory). Add an env to the config:

[mcp_servers.callflow]
command = "npx"
args = ["-y", "pi-callflow@latest"]
env = { CALLFLOW_CWD = "/Users/you/dev/your-project" }

Notes for MCP:

• The server logs only to stderr (stdout is the protocol channel).
• MCP has no "turn end" event, so the window opens immediately on the tool call rather than when the agent finishes (that timing difference is the only behavioral gap vs pi).

Editor jump

Clicking a step opens the file in your editor. The top bar shows an “open in” selector listing only the editors actually installed on your machine (detected via command -v): VS Code, Cursor, IntelliJ IDEA, Sublime. Pick one; clicks use it.

To force a specific command (and lock the selector), set an env override:

export CALLFLOW_OPEN_CMD='idea --line {line} {file}'   # IntelliJ
export CALLFLOW_OPEN_CMD='code -g {file}:{line}'        # VS Code

Linux / WSL

The viewer is a Glimpse window. On Linux, Glimpse has two backends and auto-selects between them:

• Native (Rust + GTK4 + WebKitGTK) — fast, but needs those dev packages installed.
• Chromium (CDP) — zero-compile; it just needs a Chromium-based browser (Chrome, Chromium, Brave, Edge) on the system. If the native binary isn't present, Glimpse falls back to this automatically. Force it with GLIMPSE_BACKEND=chromium.

Either backend renders the full interactive window (clickable steps → editor jump). What both need is a GUI/display.

WSL2 — recommended: a real interactive window via WSLg

WSL2 on Windows 11 (and recent Windows 10) ships WSLg, which gives your Linux distro a working display. Two steps and you get the real Call Flow window:

# 1) confirm WSLg is providing a display (should print something, e.g. :0 or wayland-0)
echo "$DISPLAY $WAYLAND_DISPLAY"

# 2) install a Chromium-based browser inside WSL so Glimpse's Chromium backend can render
sudo apt install chromium-browser        # Debian/Ubuntu (or install Google Chrome)

That's it — Glimpse detects no native binary, uses the Chromium backend, and the window opens under WSLg with full interactivity. (Prefer the native backend? Install the GTK4/WebKitGTK dev packages from the Build-from-source notes instead; either works.)

WSL2 without a display — degraded fallback to the Windows browser

If WSLg isn't available (or you don't want a Linux GUI), Glimpse can't open a window, so callflow falls back to writing the diagram to a temp HTML file and opening it in your Windows browser. Plain xdg-open usually does nothing on WSL, so callflow detects WSL and uses wslview (or explorer.exe with a translated path). Install wslu so this works cleanly:

sudo apt install wslu          # provides wslview

This fallback is static — you see the diagram, but clicking a step to jump to your editor won't work (there's no live channel back to WSL). Use the WSLg path above for the full experience.

Advanced: CALLFLOW_BROWSER overrides the fallback opener (use {file} for the HTML path). It's most useful on plain Linux — e.g. CALLFLOW_BROWSER='firefox {file}'. On WSL, pointing it at a Windows .exe needs a Windows path (wslpath -w), which is exactly what the built-in wslview/explorer.exe fallback already handles for you.

Offline / closed networks

The viewer HTML is fully self-contained: mermaid is bundled inline at build time (no CDN), so it renders identically on air-gapped / corporate networks. If the native Glimpse window can't launch (no toolchain), it falls back to opening the diagram in the system browser.

Develop

npm install
npm run build        # build:web (esbuild → self-contained web/dist/index.html) + tsc check
npm run smoke        # opens the real window with a sample diagram, auto-closes in 4s

After editing web/src/*, re-run npm run build:web.

Status

MVP. See HANDOFF.md for the full design record, decisions, and roadmap.