Skip to content

usage.md

Latest commit

 

History

History
164 lines (133 loc) · 6.36 KB

usage.md

File metadata and controls

164 lines (133 loc) · 6.36 KB
Raw

Usage and configuration

Back to the README

Sessions and retention

Manage saved tours in Settings → Manage sessions or from the CLI:

diffcompass sessions
diffcompass sessions --all
diffcompass sessions resume 169dedd6 --open
diffcompass sessions rename 169dedd6 "Push notification review"
diffcompass sessions archive 169dedd6
diffcompass sessions unarchive 169dedd6
diffcompass sessions delete 169dedd6 --yes
diffcompass sessions prune --repo . --days 30 --max 50 [--yes]

Sessions live under ${XDG_STATE_HOME:-~/.local/state}/diffcompass/sessions and are written atomically. Pruning previews by default, honors repository retention defaults, preserves archived sessions unless requested, and can remove stale tool-owned temporary directories with --temp-hours N. Process locks protect active sessions and proposal/bridge workspaces; paths and freshness are rechecked before deletion. PR worktrees are removed only from the tool-owned state directory and only when clean.

Completed PR reviews remove their temporary worktree when the review server shuts down, after the attached agent acknowledges the result or its delivery timeout expires. Interrupted reviews and worktrees with local changes are kept. The saved review remains available; reopening a completed review recreates its checkout at the recorded PR revision when needed.

External tools can find a running review through <session>.json.lock beside its saved session. The lock keeps its existing pid, token, and startedAt fields and adds reviewUrl once the server is listening. Attached sessions also include bridgeUrl, the bridge's base URL. These fields are absent during early startup and disappear when the lock is removed at shutdown.

Match the saved session's repositoryRoot to the repository, then verify that the lock's pid is alive before opening reviewUrl. For PR reviews, the original checkout is in pullRequest.sourceRepositoryRoot. Ignore locks with dead PIDs; reopening that session replaces a stale lock. The lock is written atomically with mode 0600. Treat reviewUrl as a credential: it includes the browser token and must not be copied into logs or shared status output. The lock's existing token is its ownership token, not the browser or attached-agent authentication token.

Comparison base

When --base is omitted, resolution uses:

  1. branch.<current>.reviewTourBase from local Git config;
  2. origin/HEAD;
  3. origin/main, origin/master, main, or master.

For a stacked branch:

git config branch.my-feature.reviewTourBase parent-feature

Review media

Pass each QA capture or recording with --media PATH (PNG, JPEG, GIF, WebP or MP4). Media shows only those session-owned files by default; its count excludes images from the diff. With no supplied media, the tab is hidden. Changed PNGs remain available in Changes with their captured before/after comparison.

To include changed PNGs in Media as well, add --media-include-changed-images to a branch or diffcompass pr launch, or set this repository default:

{ "media": { "includeChangedImages": true } }

Each available side contributes one item (two for a modified PNG, one for an added or deleted PNG). These optional images load when scrolled into view or explicitly opened, rather than during page startup. Supplied --media files keep their existing import and loading behavior.

The choice is saved with the session. On resume, an explicit CLI flag wins over the saved choice; the saved choice wins over repository configuration. Older sessions without a saved choice use the repository default, which is false unless opted in.

Repository defaults

Add .diffcompass.json at the repository root:

{
  "base": "origin/main",
  "agent": "codex",
  "model": "gpt-5.6",
  "reasoning": "high",
  "diff": {
    "layout": "split",
    "changedFilesOnly": true,
    "contextLines": 25
  },
  "review": {
    "requireAllFilesReviewed": true,
    "closeOutcome": "accepted"
  },
  "analysis": {
    "instructions": [
      "Treat authentication and persisted-session changes as high risk."
    ],
    "findings": {
      "enabled": true,
      "categories": ["correctness", "security", "testing"],
      "minimumSeverity": "medium"
    }
  },
  "retention": {
    "maxAgeDays": 30,
    "maxSessions": 50,
    "includeArchived": false
  }
}
Setting Bounds and precedence
diff.contextLines 3–200
review.closeOutcome accepted or cancelled; cancelled exposes only Cancel review
analysis.instructions Up to 32 distinct instructions, 2,000 characters each
Finding categories Up to 32 names
Minimum severity low, medium, high, or critical
Precedence Explicit CLI values → repository defaults → built-in/Git-inferred defaults

Unknown settings fail closed. Resumed sessions retain their original settings. Repository instructions cannot override read-only execution, evidence rules, or the response contract. Component maps, call flows, sequence diagrams, adaptive diagrams, and findings start enabled; disabling one skips its generation work.

Attached-agent protocol

The launching agent must keep serving authenticated bridge events; invoking the CLI alone does not provide a responder. The bundled skill documents the long-lived watcher, bounded polling fallback, and response schemas.

  • --attached --open implies --start-tour, preparing the outline and first explanation before opening one user-facing page.
  • Future stops prepare concurrently inside the configured window; questions bypass that queue.
  • Browser and bridge tokens are separate. Browser mutations require same-origin requests; the bridge token uses an owner-only temporary file.
  • Closing sends the outcome, overall note, and feedback to the same agent.
  • Feedback includes the reviewed Git tree. Passing it back through --base scopes a follow-up tour to feedback-induced changes.
  • A lost attached heartbeat may use the local fallback, but edits remain request-gated and isolated.

Standalone agents remain read-only, although reviewers can still author edit suggestions.

Upgrading from version 1

Version 2 uses the diffcompass command and skill, .diffcompass.json, and DIFFCOMPASS_* environment variables. Installations and saved sessions now live under the diffcompass directories. Previous installations and saved data are not deleted or automatically migrated.