• Check

  gh

  is installed and authenticated: run

  gh auth status

  . If not authenticated, stop and ask the user to run

  gh auth login

  .
• Verify the current repo matches the PR's repo: run

  gh repo view --json nameWithOwner -q .nameWithOwner

  and confirm it matches the

  owner/repo

  in the URL. If it doesn't, stop and tell the user they need to be inside the PR's repository clone — diffity can't tour a PR for a repo you don't have checked out.
• Start diffity against the PR: run

  diffity --no-open <pr-url>

  using the Bash tool with

  run_in_background: true

  . The

  --no-open

  flag must come BEFORE the URL — commander's

  passThroughOptions()

  will slurp any flag that appears after the positional URL into the refs array, skipping PR handling and producing an "unknown ref" error. This command checks out the PR's branch locally and starts a diff-scoped session. Wait 2 seconds, then run

  diffity list --json

  to get the port. You do not also need a tree instance — the diff session supports

  agent tour-*

  commands.

diffity list --json

• If no instance is running, start one: run

  diffity tree --no-open

  using the Bash tool with

  run_in_background: true

  , wait 2 seconds, then run

  diffity list --json

  to get the port.

• "How does X work?" → assume someone new to this codebase — explain architectural decisions, not just code mechanics
• "Why does X do Y?" → assume someone debugging or reviewing — focus on the reasoning and edge cases
• "Walk me through X" → assume someone who wants the full picture — be thorough, include context

git log --reverse <base>..HEAD

abc1234

gh

• gh pr view <url> --json title,body,baseRefName,headRefName,commits,files

  — PR title, body, base/head branches, commit list, and changed-file list. The PR body often contains the richest "why" (design context, screenshots, trade-offs the author considered) — quote or summarize it in the intro.

• gh pr diff <url>

  — the unified diff that defines the tour's scope. Use this to confirm the full surface area, not just what you see in

  git diff

  .
• Use the PR's

  baseRefName

  (from the JSON above) as the diff base — not

  master

  /

  main

  by default. Commands like

  git log --reverse <baseRefName>..<headRefName>

  walk the PR's commits in author order.
• Source files are readable from the working tree because

  diffity <pr-url>

  has already checked out the PR branch locally.

diffity agent tour-start --topic "<short title>" --body "<intro>" --json

--topic

• The key components/packages/modules involved and their responsibilities
• How they connect — data flow, call chains, or dependency relationships
• Key abstractions or patterns the reader should know about
• A summary flow diagram using bold text (e.g. CLI args → git diff → parser → JSON API → React render)
• Configuration context — if the feature's behavior depends on config, environment variables, or feature flags, mention them here so the reader knows what mode/state the tour assumes

code

diffity agent tour-step --tour <id> --file <path> --line <start> --end-line <end> --body "<narrative>" --annotation "<short label>" --json

• --file

  : Path relative to repo root (e.g.

  src/server.ts

  )

• --line

  /

  --end-line

  : The exact line range to highlight. Keep it focused on the relevant section.

• --annotation

  : A short label (3-6 words) shown as the step title. Think of it as a chapter heading.

• --body

  : The narrative shown in the explanation panel. This has generous space — use it to write thorough explanations using markdown:

tour-step

--file

--line

--end-line

goto:

1. Transition (1 sentence): connect to the previous step — see the examples below.
2. Explanation (the bulk): what this code does and why it's structured this way — design decisions, trade-offs, concrete examples. Use sub-highlights (

   focus:X-Y

   ) if the range breaks into distinct sections.
3. Takeaway (1-2 sentences): a gotcha, edge case, or "this is what you'd touch if..." pointer.

• "Now that we've seen how the request is parsed, let's look at where it gets validated..."
• "The handler we just saw delegates to this service, which is where the actual business logic lives..."
• "At this point the data has been transformed and is ready to be persisted — here's how that happens..."

• Write in prose paragraphs, supplemented by structured content where it helps
• Use

  code

  for function names, variables, refs, commands. When referencing a function, class, or code symbol that lives in a known file and line, make it a goto link so the reader can click to jump there. Syntax:

  [`symbolName`](goto:path/to/file.ts:startLine-endLine)

  or

  [`symbolName`](goto:path/to/file.ts:line)

  for a single line. These render as clickable inline code that navigates to the file and highlights the target lines. Example:

  [`handleDragEnd`](goto:src/KanbanContent.jsx:42-58)

  . Use plain backtick code for generic terms, CLI commands, or symbols you haven't located in the codebase.
• Use bold for key concepts being introduced
• Explain why the code exists and the design decisions behind it, not just what it does
• Use concrete examples: "When you run

  diffity main

  , this line calls

  normalizeRef('main')

  which computes

  git merge-base main HEAD

  "
• Use tables for mappings (input → output, ref → git command)
• Use code blocks for data structures or command outputs
• Connect each step to the bigger picture from the intro
• Call out edge cases and gotchas — if there's a non-obvious behavior, a known limitation, or a "this looks wrong but it's intentional" moment, flag it. These are the things that trip people up when they work on this code later.
• For large highlighted ranges, use sub-highlight links to focus on specific sub-sections within the step. Syntax:

  [label](focus:startLine-endLine)

  . These render as clickable chips that shift the highlight to the specified lines. Example:
  markdown

  First, the function validates its parameters:
  [Parameter validation](focus:15-22)
  
  Then the core transform processes each entry:
  [Core transform](focus:25-40)
  
  Finally, results are cached before returning:
  [Result caching](focus:42-48)

  Use sub-highlights when a step covers 30+ lines and the narrative naturally breaks into distinct sections. The line ranges must be within the step's

  --line

  /

  --end-line

  range.

• The intro (step 0) overview: a flow showing how components connect
• Steps involving multi-component interactions or request flows
• State machines or lifecycle transitions

• graph TD/LR

  for architecture, module dependencies, data flow

• sequenceDiagram

  for call chains, request/response flows

• stateDiagram-v2

  for state machines, lifecycle transitions

• classDiagram

  for type hierarchies, struct relationships

• flowchart

  for algorithms, decision trees, control flow

• Write a wall of bullet points — use prose paragraphs with formatting
• Just describe the syntax — explain the design decisions
• Repeat information visible in the highlighted code
• Use headers in step bodies (the annotation serves as the title)
• Force a diagram into every step — only add one when it genuinely helps
• Start a step without connecting it to the previous one

• Summarizes the full flow in 2-3 sentences — now that the reader has seen every piece, give them the zoomed-out mental model they can carry forward
• Highlights the key design decisions — what are the 2-3 most important architectural choices in this code, and why were they made?
• Points out extension points — if someone wanted to modify or extend this feature, where would they start? What files would they touch?
• Notes related areas — mention 1-2 related features or flows that connect to this one, so the reader knows where to explore next

"Putting It Together"

Your tour is ready — check your browser.