nilbuild / nilbuild/diffity

Add `diffity agent open` to open the agent's current session in the browser

Open
#38 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
775
Forks
57
PR merge metrics
No merged PRs in 30d

Description

Version 0.9.5, macOS, Node 24.

An agent that starts diffity with --no-open, reviews a diff, and posts comments has no
supported way to open the browser at the session it just worked on.

Opening a known ref is already covered by diffity open [ref]. The gap is the other case: the
agent wants the session its own comments went to, and it cannot name that session as a ref.

To solve this problem an additional command could be implemented.

What happens today

  1. diffity --no-open --quiet main..feature, which the bundled diffity-review skill mandates
    in step 1
  2. The agent reviews and posts comments through diffity agent comment
  3. The agent tries to hand the human a URL

At step 3, diffity open with no argument produces /diff with no query, the UI defaults to
ref=work, and a clean checkout shows "No changes found". The human sees an empty page and
concludes the review never ran.

Reconstructing the ref instead does not work reliably. diffity list --json exposes a ref per
instance, but that is the launch ref, and the agent's comments belong to the session named by
current-session. The two disagree whenever anything has touched the pointer since launch,
which a single browser page view is enough to do:

instance launch ref (diffity list):    HEAD~1
agent session ref (current-session):   main..feature

Passing the launch ref then opens a valid diff of the same files with none of the comments on
it, so the workaround does not just read awkwardly, it silently opens the wrong page.

diffity agent comment writes to current session, so this reaches further than
opening a URL. Navigating to a stale tab with a different ref while a review is running changes the
current session under the agent, and every comment posted after that lands in the stale opened
session instead of the one being reviewed. diffity agent list and diffity agent diff read the
same pointer, so the agent sees the stale session's contents and gets no signal that anything
moved. (I think it worth opening separate issue for this browser tab switching problem)

Proposed behavior

diffity agent open opens the browser at the agent's current session and prints the URL, the way
the other commands do. No arguments. An agent that wants a specific ref already has
diffity open [ref], so there are two commands and no overlap between them.

Example implementation:

agent.command("open")
  .description("Open the browser at the agent's current session")
  .action(async () => {
    const existing = findInstanceForRepo(repoHash);
    const ref = getCurrentSession()?.ref;
    const qs = ref ? `?${new URLSearchParams({ ref })}` : "";
    await open(`http://localhost:${existing.port}/diff${qs}`);
  });

The skill needs the same fix

skills/diffity-review/SKILL.md has the problem baked in. Step 1 requires --no-open, which
suppresses the one place the correct ?ref= URL gets printed. Step 4 then runs diffity open <ref>
using the ref argument passed to the skill, which is absent whenever the session came from
--base and --compare. Following the skill exactly on a branch review ends with the human
looking at an empty working tree.

Once agent open exists, step 4 becomes diffity agent open with no ref to reconstruct.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing the existing diffity open, diffity agent comment, diffity agent list, and diffity agent diff command entry points and how they find the current session. Update skills/diffity-review/SKILL.md as described. Done when diffity agent open opens and prints the current session URL without arguments, and the skill uses it instead of reconstructing a ref.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
cli, documentation
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.