Interactive, visual code exploration for the AI era

AI-Powered · Terminal-Native · Diagram-Enhanced

An AI agent skill and interactive TUI that generates step-by-step code walkthroughs enriched with diagrams, code snippets, and full-text search. Built for developers who need to understand codebases — fast.

• AI-Driven Analysis — A Claude Code skill analyzes your codebase and produces structured walkthrough JSON, tracing execution flows or mapping architecture
• Interactive TUI — Navigate walkthroughs in the terminal with keyboard-driven step browsing, table of contents, and bookmarks
• Mermaid Diagrams — Sequence, flowchart, and class diagrams rendered as ASCII art directly in your terminal
• Full-Text Search — Instantly search across titles, explanations, code snippets, and diagrams
• Export — Generate Markdown or HTML documentation from any walkthrough
• Bookmarks — Save and revisit important steps across sessions

go install github.com/4thel00z/code-walkthrough/...@latest

git clone https://github.com/4thel00z/code-walkthrough.git
cd code-walkthrough
go build -o walkthrough ./cmd/walkthrough

walkthrough install

This installs the AI agent skill and JSON schema to .claude/skills/code-walkthrough/.

In Claude Code, invoke the skill:

/code-walkthrough

Choose a scope:

The agent analyzes the repository and writes a walkthrough to .walkthrough/walkthrough.json.

walkthrough view

This defaults to .walkthrough/walkthrough.json. You can also specify a path explicitly:

walkthrough view path/to/walkthrough.json

walkthrough export walkthrough.json output.md --format=markdown
walkthrough export walkthrough.json output.html --format=html

The project follows hexagonal architecture with clear separation of concerns:

cmd/walkthrough/       Entry point
domain/                Core entities, navigation, search (zero dependencies)
application/           Use cases — navigate, search, bookmark, export, install
port/                  Inbound & outbound interfaces
adapter/               CLI (Cobra), TUI (Bubble Tea), filesystem, Mermaid renderer
skilldata/             Embedded AI agent skill & JSON schema
schema/                Walkthrough JSON schema

Walkthroughs conform to a JSON schema. The core structure:

Walkthrough
├── title, scope (flow | overview), repository
└── sections[]
    ├── id, title, description
    └── steps[]
        ├── id, title, explanation
        ├── codeSnippet? — filePath, language, lines, source
        └── diagram? — type (sequence | flowchart | classDiagram), mermaid DSL

MIT