https://github.com/uptick/linear-walkthrough
A claude code friendly cli tool to visualize markdowns for the purpose of linear code walkthroughs
https://github.com/uptick/linear-walkthrough
Last synced: about 2 months ago
JSON representation
A claude code friendly cli tool to visualize markdowns for the purpose of linear code walkthroughs
- Host: GitHub
- URL: https://github.com/uptick/linear-walkthrough
- Owner: uptick
- License: mit
- Created: 2026-03-05T09:07:47.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-12T03:02:47.000Z (5 months ago)
- Last Synced: 2026-04-07T12:07:28.346Z (4 months ago)
- Language: HTML
- Size: 363 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# linear-walkthrough
Generate self-contained, GitHub-styled HTML walkthroughs from GFM markdown.
Takes markdown files with code walkthroughs and produces single-file HTML pages with syntax highlighting, dark mode support, and Mermaid diagram rendering. Optionally launches an interactive server where you can select text and ask Claude follow-up questions.
## Install
```bash
# Run directly from GitHub
uvx --from git+https://github.com/uptick/linear-walkthrough linear-walkthrough input.md -o output.html
# Or install locally
uv pip install git+https://github.com/uptick/linear-walkthrough
linear-walkthrough input.md -o output.html
```
## AI Coding Assistants
Add the skill to your AI coding assistant:
```bash
npx skills add uptick/linear-walkthrough
```
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf.
Example prompts:
```
/linear-walkthrough Walk me through the auth module
/linear-walkthrough Create a walkthrough for PR #42
/linear-walkthrough Give me a beginner-friendly walkthrough of the API layer
```
## Quick Start
```bash
# File input → file output
uv run linear-walkthrough input.md -o output.html
# Stdin → stdout
cat input.md | uv run linear-walkthrough -o out.html
# Interactive server mode (opens browser)
uv run linear-walkthrough input.md --serve
```
## Features
- **GFM markdown** — tables, task lists, fenced code blocks
- **Syntax highlighting** — Pygments with light/dark theme support via `prefers-color-scheme`
- **Mermaid diagrams** — rendered client-side from fenced `mermaid` blocks
- **Self-contained output** — single HTML file with all CSS inlined
- **Interactive mode** — select text in the browser, ask Claude follow-up questions, responses appended to the source file
## Interactive Server Mode
```bash
uv run linear-walkthrough walkthrough.md --serve [-p PORT] [--cwd DIR]
```
Starts a local HTTP server (default port 7847) that renders your walkthrough with a text selection UI. Select any text and ask a question — Claude responds using the full walkthrough as context. Follow-up responses are appended to the original markdown file.
## Project Structure
```
linear_walkthrough/
cli.py - CLI entry point
renderer.py - Markdown → HTML via markdown-it-py + Pygments
template.py - Minijinja template loader + CSS
server.py - Interactive server mode (stdlib http.server + claude subprocess)
templates/
page.html - Static output template
page_interactive.html - Interactive template with follow-up JS
```
## Tech Stack
- **Python 3.12+** managed with **uv**
- **markdown-it-py** — GFM parsing
- **Pygments** — syntax highlighting
- **minijinja** — HTML templating
- **Mermaid.js** — diagram rendering (CDN)
## Development
```bash
uv run ruff check . # lint
uv run mypy . # type check
uv run pytest # test
```