📖 github-mobile-reader

Transform GitHub PR diffs into mobile-friendly Markdown — understand what changed per function without reading long code.

한국어 문서 →

The Problem

GitHub's mobile web renders code in a fixed-width monospace block. Long lines require horizontal scrolling, and deeply nested logic is impossible to read on a commute.

The Solution

github-mobile-reader parses a git diff and produces a per-function summary — showing what each function/component added, removed, or changed rather than raw line diffs.

Example Output

## 📄 `src/components/TodoList.tsx`

> 💡 Previously fetched all tasks unconditionally. Now accepts filter and sortOrder
> params — fetchTasks is called conditionally and filter state drives re-fetching.

**Import changes**
+ `FilterBar`
+ `useSortedTasks`
- `LegacyLoader` (removed)

**✏️ `TodoList`** _(Component)_ — changed
  변수: `filter`, `sortOrder`

**✏️ `fetchTasks`** _(Function)_ — changed
  파라미터+ `filter`
  파라미터+ `sortOrder`
  + (API) `fetchTasks(filter)` → `tasks`

**✅ `handleFilterChange`** _(Function)_ — added
  파라미터+ `field`
  파라미터+ `value`
  + (setState) `setFilter({...filter, [field]: value})`

Features

Per-function summaries — each function/component gets its own line with status (added / removed / changed); no headings, normal font size on mobile
Side-effect labels — behavior lines are prefixed with (API), (setState), (state), (cond), (catch), (guard) so you can tell at a glance what kind of change it is
Guard clause detection — if (!x) return patterns surfaced as (guard) early return entries
Import changes — newly added or removed imports at the file level
Parameter changes — added or removed function parameters
Variables — simple variable assignments attached to the nearest function shown inline
UI changes — added/removed JSX components (generic tags like div, span are filtered); map (🔄) and conditional (⚡) patterns
Props changes — TypeScript interface/type member changes (long string values abbreviated to '...')
Gemini AI summaries (optional) — focuses on business logic change and side effects, not raw lines (> 💡 ...)
Secure by default — tokens are injected via environment variables only; no flag that leaks to shell history

CLI Usage

Run directly with npx — no setup or config file needed.

Authentication

export GITHUB_TOKEN=ghp_xxxx

Security note: The CLI does not accept a --token flag. Passing secrets as CLI arguments exposes them in shell history and ps output.

Single PR

npx github-mobile-reader --repo owner/repo --pr 42

Single PR with Gemini AI summaries

GEMINI_API_KEY=AIzaSy... npx github-mobile-reader --repo owner/repo --pr 42

All recent PRs

npx github-mobile-reader --repo owner/repo --all --limit 20

Options

Flag	Default	Description
`--repo`	(required)	Repository in `owner/repo` format
`--pr`	—	Process a single PR by number
`--all`	—	Process all recent PRs (use with `--limit`)
`--out`	`./reader-output`	Output directory — relative paths only, no `..`
`--limit`	`10`	Max number of PRs to fetch when using `--all`
`--gemini-key`	—	Gemini API key (or set `GEMINI_API_KEY` env var)

Token: read from $GITHUB_TOKEN (60 req/hr unauthenticated, 5,000 req/hr authenticated).

Each PR produces one file: reader-output/pr-<number>.md

GitHub Action

Automatically generates a Reader document and posts a comment on every PR.

Step 1 — Add the workflow file

Create .github/workflows/mobile-reader.yml:

name: 📖 Mobile Reader

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: write       # commit the generated .md file
  pull-requests: write  # post the PR comment

jobs:
  generate-reader:
    name: Generate Mobile Reader View
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          base_branch: ${{ github.base_ref }}
          output_dir: docs/reader
          gemini_api_key: ${{ secrets.GEMINI_API_KEY }}  # optional
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Post PR Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const path = './reader-output/pr-${{ github.event.pull_request.number }}.md';
            if (!fs.existsSync(path)) { console.log('No reader file generated.'); return; }
            const body = fs.readFileSync(path, 'utf8');
            const comments = await github.rest.issues.listComments({
              owner: context.repo.owner, repo: context.repo.repo,
              issue_number: ${{ github.event.pull_request.number }},
            });
            const prev = comments.data.find(c =>
              c.user.login === 'github-actions[bot]' && c.body.startsWith('# 📖 PR #')
            );
            if (prev) await github.rest.issues.deleteComment({
              owner: context.repo.owner, repo: context.repo.repo, comment_id: prev.id,
            });
            await github.rest.issues.createComment({
              owner: context.repo.owner, repo: context.repo.repo,
              issue_number: ${{ github.event.pull_request.number }}, body,
            });

Step 2 — Open a PR

Every subsequent PR will automatically receive:

A Reader Markdown file at docs/reader/pr-<number>.md
A summary comment on the PR

Action Inputs

Input	Required	Default	Description
`github_token`	✅	—	Use `${{ secrets.GITHUB_TOKEN }}`
`base_branch`	❌	`main`	Base branch the PR is merging into
`output_dir`	❌	`docs/reader`	Directory for generated `.md` files
`gemini_api_key`	❌	—	Gemini API key — omit to disable AI summaries

Gemini AI Summaries (optional)

Even complex hooks like useCanvasRenderer (200+ lines) get summarized in 1–3 sentences. Without an API key, behavior is identical — no errors, no fallback output.

Uses Gemini 2.5 Flash Lite — fast, low-cost, no thinking overhead.

Get a free API key

aistudio.google.com/apikey

CLI

# via environment variable (recommended)
GEMINI_API_KEY=AIzaSy... npx github-mobile-reader --repo owner/repo --pr 42

# via flag
npx github-mobile-reader --repo owner/repo --pr 42 --gemini-key AIzaSy...

GitHub Action

Go to Settings → Secrets and variables → Actions → New repository secret
Name: GEMINI_API_KEY, Value: your key
Add gemini_api_key: ${{ secrets.GEMINI_API_KEY }} to the workflow (see example above)

Security: GitHub Secrets are masked in all workflow logs and never exposed in plain text.

Output Format

# 📖 PR #7 — feat: add task filtering and sort controls

> Repository: owner/repo
> Commit: `3f8a21c`
> Changed JS/TS files: 3

---

## 📄 `src/components/TodoList.tsx`

> 💡 Previously fetched all tasks unconditionally. Now accepts filter and sortOrder
> params — fetchTasks is called conditionally and filter state drives re-fetching.

**Import changes**
+ `FilterBar`
+ `useSortedTasks`
- `LegacyLoader` (removed)

**✏️ `TodoList`** _(Component)_ — changed
  변수: `filter`, `sortOrder`
  + (상태) `filter` ← `useState({})`
  + `useEffect` [filter] 변경 시 실행

**✏️ `fetchTasks`** _(Function)_ — changed
  파라미터+ `filter`
  파라미터+ `sortOrder`
  + (guard) `!filter` → early return
  + (API) `api.getTasks(filter)` → `tasks`

**✅ `handleFilterChange`** _(Function)_ — added
  파라미터+ `field`
  파라미터+ `value`
  + (setState) `setFilter({...filter, [field]: value})`

**✏️ `TaskCard`** _(Component)_ — changed
  Props+ `dueDate: '...'`
  + (cond) `!task.completed`
  UI: `<Badge>`

Symbol classification

Label	Meaning
`✅ ... — added`	Function/component newly introduced in the diff
`❌ ... — removed`	Function/component deleted in the diff
`✏️ ... — changed`	Existing function/component with modified content
`변수: x, y`	Simple variable assignments collapsed inline

Line prefixes

Prefix	Meaning
`(API)`	`await` call — fetches data from a server or external service
`(setState)`	`setState` call — updates React state
`(state)`	Hook assignment — `const x = useHook()`
`(cond)`	`if / else if` branch
`(guard)`	Guard clause — `if (!x) return` early-exit pattern
`(catch)`	`catch` block
`(return)`	Non-trivial return value
`파라미터+` / `파라미터-`	Function parameter added / removed
`Props+` / `Props-`	TypeScript interface/type member added / removed
`UI:`	JSX component added or removed

npm Library Usage

npm install github-mobile-reader

import { generateReaderMarkdown } from 'github-mobile-reader';
import { execSync } from 'child_process';

const diff = execSync('git diff HEAD~1 HEAD', { encoding: 'utf8' });
const markdown = generateReaderMarkdown(diff, {
  pr: '42',
  commit: 'a1b2c3d',
  file: 'src/api/users.ts',
  repo: 'my-org/my-repo',
});

console.log(markdown);

Public API

import {
  generateReaderMarkdown,  // diff → complete Markdown document
  parseDiffHunks,          // diff → DiffHunk[]
  attributeLinesToSymbols, // DiffHunk[] → SymbolDiff[]
  generateSymbolSections,  // SymbolDiff[] → string[]
  extractImportChanges,    // detect added/removed imports
  extractParamChanges,     // detect added/removed function parameters
} from 'github-mobile-reader';

`generateReaderMarkdown(diffText, meta?)`

Parameter	Type	Description
`diffText`	`string`	Raw `git diff` output
`meta.pr`	`string?`	Pull request number
`meta.commit`	`string?`	Commit SHA
`meta.file`	`string?`	File name
`meta.repo`	`string?`	Repository in `owner/repo` format

Returns: string — the complete Markdown document.

`SymbolDiff`

interface SymbolDiff {
  name: string;
  kind: 'component' | 'function' | 'setup';
  status: 'added' | 'removed' | 'modified';
  addedLines: string[];
  removedLines: string[];
}

Language Support

The parser is optimized for JS/TS syntax patterns.

Language	Extensions	Support
JavaScript	`.js` `.mjs` `.cjs`	✅ Full
TypeScript	`.ts`	✅ Full
React JSX	`.jsx`	✅ Full
React TSX	`.tsx`	✅ Full
Others	—	🔜 Planned

Project Structure

github-mobile-reader/
├── src/
│   ├── parser.ts    ← diff parsing and symbol analysis (core logic)
│   ├── gemini.ts    ← Gemini 2.5 Flash Lite AI summaries (opt-in)
│   ├── index.ts     ← public npm API
│   ├── action.ts    ← GitHub Action entry point
│   ├── cli.ts       ← CLI entry point
│   └── test.ts      ← smoke tests (npx ts-node src/test.ts)
├── dist/            ← compiled output (auto-generated)
├── reader-output/   ← CLI output directory (gitignored)
├── action.yml       ← GitHub Action definition
└── package.json

Contributing

git clone https://github.com/3rdflr/github-mobile-reader.git
cd github-mobile-reader
npm install
npm run build:all        # build library + Action + CLI
npx ts-node src/test.ts  # run smoke tests

Pull requests are welcome.

License

MIT © 3rdflr

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.github/workflows		.github/workflows
docs/reader		docs/reader
src		src
.gitignore		.gitignore
README.ko.md		README.ko.md
README.md		README.md
action.yml		action.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

3rdflr/github-mobile-reader

Folders and files

Latest commit

History

Repository files navigation

📖 github-mobile-reader

The Problem

The Solution

Example Output

Features

Table of Contents

CLI Usage

Authentication

Single PR

Single PR with Gemini AI summaries

All recent PRs

Options

GitHub Action

Step 1 — Add the workflow file

Step 2 — Open a PR

Action Inputs

Gemini AI Summaries (optional)

Get a free API key

CLI

GitHub Action

Output Format

Symbol classification

Line prefixes

npm Library Usage

Public API

generateReaderMarkdown(diffText, meta?)

SymbolDiff

Language Support

Project Structure

Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Contributors 3

Uh oh!

Languages

`generateReaderMarkdown(diffText, meta?)`

`SymbolDiff`

Packages