Gloss

Gloss

Line-by-line explanations for AI-written code — a reviewable .gloss/ doc mirror plus a single-file, git-diff-style viewer.

As AI writes more of our code, the human bottleneck shifts from writing to reading. Gloss turns "human reads code" into "human reads explanations, with the code alongside":

• A skill (SKILL.md) — runs inside any skills-capable coding agent (ZCode, Claude Code, …). Give it a file, a directory, or a whole project; it writes one explanation document per source file into .gloss/ at the project root, mirroring the directory structure, with one explanation row per meaningful source line plus a file-level summary. Blank, comment-only, pure-symbol (}), and import lines are tracked as explicit skipped ranges instead of noise rows; build output, i18n dictionaries, config/IDE files are excluded by default. Explanations are written in whatever language the user asks in.
• A viewer (assets/viewer.html) — one dependency-free HTML file, fully local. File tree on the left; code and explanations aligned line by line on the right, diff-style; a project-overview dashboard of file summary cards and coverage. UI language switches between Chinese and English.

Quick start (no skill needed)

1. Open assets/viewer.html in Chrome or Edge.
2. Click Demo / 内置示例 — you'll see the overview dashboard and the line-by-line comparison immediately.
3. Or drop the demo/ folder onto the page to exercise the real file-loading path.

Install as a skill (30-second setup)

Gloss is a plain skill folder — a SKILL.md plus reference/, scripts/, and assets/. Clone the repo into your agent's skills directory, named gloss. Click your agent:

ZCode

git clone https://github.com/RecursiveVar/Gloss.git ~/.agents/skills/gloss

• User scope (every project): ~/.agents/skills/gloss/ (the cross-agent convention) or ~/.zcode/skills/gloss/ (ZCode only).
• Project scope: <project>/.zcode/skills/gloss/.
• Update: git pull. Skills load at session start, so start a new session after installing.

Claude Code

git clone https://github.com/RecursiveVar/Gloss.git ~/.claude/skills/gloss

• User scope: ~/.claude/skills/gloss/; project scope: <project>/.claude/skills/gloss/.
• Update: git pull.

Codex

git clone https://github.com/RecursiveVar/Gloss.git ~/.codex/skills/gloss

• Codex treats every folder under ~/.codex/skills/ that contains a SKILL.md as a skill.
• Project scope: <project>/.codex/skills/gloss/.
• Update: git pull, then restart Codex / VS Code so the new skill is discovered.

Gemini CLI

gemini skills install https://github.com/RecursiveVar/Gloss.git --path .

• The skill sits at the repository root, hence --path .. Installs into ~/.gemini/skills/; update by re-running the command.
• On a Gemini CLI version without the skills subcommand, clone instead:

git clone https://github.com/RecursiveVar/Gloss.git ~/.gemini/skills/gloss

Any other agent

• Agents that follow the .agents convention read ~/.agents/skills/gloss/ — the ZCode command above already covers them.
• Otherwise, place the folder in any directory your agent discovers skills from; the skill itself is agent-agnostic.
• On Windows, ~ is your home directory (C:\Users\<you>); the commands above run as-is in Git Bash / WSL.

Then say things like:

• "explain src/service/OrderService.java line by line"
• "逐行解释 src/service/OrderService.java"
• "help me understand this directory / 帮我读懂这个目录下的代码"
• "generate .gloss for the whole project"

The skill confirms scope → generates docs one file at a time in your language (scopes above ~500 lines are split across sub-agents when the host tool provides them) → updates .gloss/index.md → copies the viewer to .gloss/viewer.html (never overwriting an existing copy) and writes .gloss/viewer-data.js, a self-loading snapshot. Double-clicking the viewer opens straight into your project — no folder picking; dragging the project root onto the page switches to live mode with staleness detection. Re-runs regenerate only files whose source has changed.

Document format (the 30-second version)

<project root>/src/service/OrderService.java
  → <project root>/.gloss/src/service/OrderService.java.md

Each doc = a one-line HTML meta comment (source path, line count, skipped ranges, generation time — used for staleness and coverage detection) + a labeled summary block (Summary / Key points / Depends on, English or Chinese) + a two-column table with one row per meaningful source line (blank/comment/brace/import lines are recorded in skipped instead). Plain Markdown: reviewable in git, greppable, disposable. Full spec: reference/doc-format.md.

Why a mirrored path instead of a flattened name like service.abd.md? Flattening can't distinguish dots in paths from dots in file names (a/b.c.java vs a.b/c.java collide), and the viewer couldn't reverse the mapping unambiguously.

Viewer features

• Overview dashboard (landing view): summary cards grouped by directory with language badges, coverage bars, and status (complete / partial / possibly stale); header stats for explanations, files, overall line coverage.
• File summary card: labeled Summary / Key points / Depends on / Risk lines at the top of each file — know what a file does and where the traps are before reading a single line of code.
• Line-by-line comparison: code (lightweight syntax highlighting) on the left, explanations on the right, aligned row by row with line numbers on both sides; column headers show live counts.
• Diff-style signals: lines that are neither explained nor skipped are highlighted in yellow (missing explanation); intentionally skipped lines render as a faint ·; stale badges when the doc's recorded line count disagrees with the file, or the file changed after the doc was generated.
• Bilingual UI: one click switches the interface between 中文 and English (remembered across sessions); explanation content keeps whatever language it was written in.
• Instant-open snapshots: the skill writes a viewer-data.js next to the viewer — double-clicking .gloss/viewer.html loads the project immediately (snapshot mode, marked in the header); drag the project root for live mode.
• Loading: drag & drop the project root, folder picker (native showDirectoryPicker dialog in Chrome/Edge, avoiding the misleading "Upload" button and the "upload N files?" prompt on large repos), or built-in demo. Dark/light themes, resizable sidebar.
• Runs 100% locally — nothing is uploaded; files stay in memory.

Select the project root (where .gloss/ sits next to your sources); dropping only the .gloss folder produces "orphan" warnings.

Repository layout

├── SKILL.md                  # the skill: trigger description + workflow + quality bar
├── reference/doc-format.md   # the .gloss document format contract
├── assets/viewer.html        # single-file viewer (also copied to projects as .gloss/viewer.html)
├── scripts/                  # mechanical verifier: docs ↔ source line alignment (Node & Python)
└── demo/                     # sample project + generated .gloss/ docs

License

MIT — see LICENSE.