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.

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)

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:

• 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
• 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.

• 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)

Your tour is ready — check your browser.