pi-difit

Pi extension for local code review with difit: open a diff viewer, read the human's inline comments, and post replies — all without leaving Pi.

Repository: https://gitlab.com/mjfuertesf/pi-difit

Install

pi install npm:@mjfuertesf/pi-difit

Requires Node.js >= 21 and difit >= 5.x.

Round-trip review flow

1. Open diff — /show-diff or show_review_diff launches difit and remembers the port.
2. Human reviews — opens the browser URL difit prints, adds inline comment threads.
3. Agent reads comments — get_review_comments or /review-comments fetches all threads.
4. Agent replies or fixes — post_review_comments adds inline replies; agent also makes code changes.
5. Human re-reviews — reloads difit; agent replies appear in the existing threads.

Commands and tools

/show-diff [base] · show_review_diff({ base?: string })

Validates the git repo, resolves the base ref, computes git merge-base <base> HEAD — the commit where your branch diverged — and launches difit HEAD <merge-base> as a detached process. This matches the GitHub/GitLab three-dot PR diff: only your changes, not everything the base branch accumulated since you branched off.

difit opens the browser itself; its server self-terminates when the tab closes. Pi shows a notification with the base label, short merge-base SHA, and server URL. The port is remembered for the tools below.

Base resolution (auto-detected when no argument given):

1. Explicit ref passed as argument (error if it does not exist)
2. <remote>/main → local main (first match wins)
3. <remote>/master → local master (first match wins)

The remote is the upstream of the current branch, or the first git remote when no upstream is configured.

If the merge-base cannot be computed (no common history, shallow clone), the extension falls back to the base ref directly and emits a warning. Note: merge-base is computed from local refs — run git fetch if your local origin/main is stale.

/review-comments · get_review_comments({ port?: number })

Fetches all comment threads from the running difit server. Returns file path, line or range, diff side, and messages with author and body.

/review-comments posts the result into the conversation as a user message to trigger an agent turn. The optional port overrides the port remembered from the last launch.

Error cases:

• No server launched and no port given — prompts you to run show_review_diff first.
• Connection refused — server is gone; prompts you to relaunch.
• Empty review — explicit "No review comments yet." message.

post_review_comments({ entries: CommentEntry[], port?: number })

Posts inline threads or replies to the running difit server. Use this to reply directly to human review comments or add agent observations.

• author is always forced to "pi" — not caller-controlled.
• Each entry: type ("thread" | "reply"), filePath, position ({ side: "old" | "new", line: number | { start, end } }), body.
• A "reply" anchors by filePath + position; if no thread exists there difit creates one.
• Returns posted count and any warnings from difit.

Error cases mirror get_review_comments, plus difit validation errors (invalid position, empty body) from the API response.

difit binary

difit ships as an optional dependency and is used as a fallback. Resolution order:

1. PI_DIFIT_COMMAND env var (explicit override, always wins)
2. difit on PATH (preferred — typically newer)
3. The difit bundled with this package

If difit is not on the default PATH — for example because a per-repo .mise.toml shadows the global node version — set the override:

export PI_DIFIT_COMMAND="mise x [email protected] -- difit"

The value is split on whitespace into command + prefix args; HEAD <merge-base> is appended. difit is always spawned with NODE_ENV removed — it serves a blank dev-mode shell when it inherits NODE_ENV=development.

Development

npm test
npm pack --dry-run

Credits

Built on difit by yoshiko-pg and contributors.

License

MIT