diff-tour

Product Introduction

Definition

diff-tour is an open-source, read-only terminal user interface (TUI) command-line tool implemented in Go that transforms standard git diffs and repository changes into interactive, guided code review tours. Functioning at the intersection of AI code generation assistance and developer onboarding, diff-tour acts as an automated technical mentor by leveraging Large Language Models (LLMs) such as Claude Code, Codex CLI, Gemini CLI, OpenCode, and GitHub Copilot CLI to analyze code changes and generate structured architectural walkthroughs.

Core Value Proposition

While AI coding assistants have accelerated the sheer volume of generated code, junior and mid-level engineers frequently struggle to comprehend why code is structured in a particular manner, what senior reviewers evaluate, and how to anticipate hidden edge cases. diff-tour solves this gap by providing an interactive step-by-step navigation paradigm (using left and right arrow keys) that exposes the cognitive frameworks, risk analyses, potential failure modes, and architectural trade-offs typical of senior engineering code reviews, all while executing entirely locally within a secure, read-only sandbox environment.

Main Features

Automated Guided Tour Generation via LLM Integration

diff-tour automates the creation of architectural walkthroughs by utilizing supported CLI-based AI agents to parse git archives, diffs, and commit logs. During the generation phase (which typically spans 2 to 5 minutes), the underlying LLM cross-references the repository changes against a built-in pedagogical knowledge base of senior engineering lessons (stored within the codebase under internal/generate/lessons). The resulting output is structured JSON containing line-level references, design rationales, probing questions, and expected answers designed to teach users how to evaluate complex pull requests.

Strict Read-Only Security Sandbox and Validation Engine

To ensure absolute safety and prevent unintended repository modifications or data leaks, diff-tour executes AI tools inside heavily restricted runtime environments. For Claude Code, the tool passes strict restriction flags (--restricted, --strict-mcp-config, --tools Read,Grep,Glob, and --permission-mode dontAsk) that strip out web browsing, command execution, and non-file reading capabilities. Furthermore, diff-tour includes a validation engine that automatically cross-checks every file path and line number generated by the LLM against the actual git repository state, discarding or iteratively requesting corrections for hallucinated or invalid references up to two times before rendering.

Git-Backed Integrity and Interactive TUI Navigation

The rendering engine of diff-tour decouples the display code from the LLM outputs by reading all code snippets, file diffs, and schemas directly from real git commits within your repository history or temporary export caches. This guarantees that code displayed on the screen is always authentic, even if the LLM suggests conceptual examples (which are explicitly marked as "Example"). Users navigate the generated tour using intuitive keyboard bindings (arrow keys for progression and regression, 'q' for quitting), while the underlying cache directory is automatically purged immediately after tour generation concludes.

Problems Solved

Pain Point

Modern development teams face a severe "comprehension deficit" caused by AI-generated code. Junior and mid-level engineers accept AI code drops that function superficially but introduce subtle technical debt, race conditions, concurrency issues, rollback failures, and security vulnerabilities that standard automated testing suites fail to catch. Additionally, onboarding new team members into unfamiliar legacy codebases or massive pull requests often lacks contextual mentorship, leading to superficial code reviews and prolonged review cycles.

Target Audience

Junior Developers, Mid-Level Software Engineers, Engineering Managers, Technical Leads, Bootcamps and Computer Science Educators, Open Source Maintainers, and Enterprise Development Teams utilizing AI coding agents (Claude Code, GitHub Copilot, Codex, Gemini).

Use Cases

• AI Code Verification: Stepping through an AI-generated feature branch to evaluate underlying risks, concurrency handling, and potential scaling bottlenecks before merging.
• Developer Onboarding: Walking through historical git commits or complex pull requests in an open-source or enterprise repository to learn codebase architecture and design patterns through the lens of a senior engineer.
• Code Review Mentorship: Acting as an automated async reviewer during self-code reviews to prompt developers with critical questions regarding error handling, idempotency, and rollback safety.

Unique Advantages

Strengths & Limitations (Pros & Cons)

• Strengths:
  • Entirely read-only execution profile guarantees zero risk of unintended file modification, command execution, or network leaks from the core tool.
  • Deep integration with existing CLI LLMs (Claude, Codex, Gemini, OpenCode, Copilot) avoids forcing users into proprietary subscription silos.
  • Local caching ensures that once a tour is generated, subsequent openings are instantaneous without incurring additional LLM generation latency or token costs.
  • Teaches architectural thinking and mental models rather than just syntax checking.
• Limitations:
  • Initial tour generation requires 2 to 5 minutes of processing time depending on the size of the git diff and the chosen LLM backend.
  • Requires one of the supported AI CLI tools to be installed and authenticated on the host machine.
  • Tour formats and internal schemas may evolve rapidly across minor releases due to active development.

Key Alternatives & Differentiation

• Standard Pull Request Review Tools (GitHub, GitLab, Bitbucket PR UI): Traditional code review interfaces display raw diffs and line comments but lack interactive, pedagogical step-through tours that teach architectural thinking, prompt users with speculative debugging questions, or structure reviews around senior engineering mental models.
• AI Chatbots (ChatGPT, Claude Web, GitHub Copilot Chat): While general-purpose chat interfaces can explain code blocks when prompted manually, they require context-switching, prompt engineering, and manual file pasting. diff-tour automates context collection via git archive and git diff, validates line-reference accuracy programmatically, and delivers a dedicated TUI geared explicitly toward structured learning and diff walkthroughs.
• Interactive Documentation Tools (Tour of Go, VS Code Code Tour extensions): VS Code extensions require manual authoring of tour steps by human developers. diff-tour dynamically generates these guided tours on-demand from any raw git branch or uncommitted change using LLMs combined with curated engineering lessons.

Frequently Asked Questions (FAQ)

What is diff-tour and how does it work?

diff-tour is an open-source terminal user interface (TUI) tool written in Go that analyzes your git changes, diffs, and commit history using an LLM CLI (such as Claude Code or GitHub Copilot), and compiles them into an interactive, step-by-step guided tour. It exports tracked files into a secure temporary cache, prompts the LLM using expert code review guidelines, validates all line references for accuracy, and lets you step through the review using the left and right arrow keys.

Does diff-tour modify my files or send private data to external servers?

diff-tour is strictly read-only and never modifies, edits, or deletes files in your repository or working directory. It runs locally as a CLI binary and makes no independent network requests; however, it passes exported git repository diffs and tracked file contents to the third-party LLM CLI tool you explicitly configure (Anthropic, OpenAI, Google, or GitHub), subject to your account terms and privacy agreements with those providers. Files ignored by .gitignore (such as .env) are never exported.

Which AI tools and CLI commands are supported?

diff-tour currently supports Claude Code (claude), Codex CLI (codex), Gemini CLI (gemini), OpenCode (opencode), and GitHub Copilot CLI (copilot), provided they are installed and authenticated on your system. During your first run, the tool prompts you to select your preferred display language and LLM backend.

How can I try diff-tour without configuring an LLM or signing in?

You can test a pre-generated example tour instantly without any LLM setup or API authentication by cloning the official example repository and running the pre-built tour file: git clone https://github.com/init-co-jp/diff-tour-example && cd diff-tour-example curl -fsSLO https://raw.githubusercontent.com/init-co-jp/diff-tour/main/tours/example-coupons.en.json tour example-coupons.en.json