@williy_cole/tell

v1.2.1

Published

2 days ago

Claude Code skill that explains MR/PR diffs line-by-line, anchored to the linked issue, and renders an interactive HTML report.

Downloads

728

0High
0Medium
0Low

williy_cole

claude-code claude-code-skill opencode ai-agent skill code-review pull-request merge-request diff github gitlab

tell

A skill for Claude Code, OpenCode, Cursor, Pi, and 50+ more agents that explains pull request and merge request diffs line-by-line — anchored to the MR description and linked issue requirements — and renders the result as an interactive HTML report.

Instead of asking "what did the code change?", tell answers "why did the code change?" and "does it actually satisfy all the requirements?"

tell viewer

Try the interactive demo →

Features

Line-by-line diff explanation — every hunk explained in terms of the MR's intent, not syntax
Requirements coverage — maps each change to issue requirements; flags gaps, partial coverage, and creep
Interactive HTML report — dual-pane viewer (diff + explanation) opens automatically in the browser
Keyboard-driven navigation — vim-style keys (h/l files, j/k scroll, c coverage, Tab panel focus)
--learn mode — adds language idiom annotations per hunk (Elixir, TypeScript, JavaScript, CSS)
Caching — skips regeneration on re-runs; --force to bust the cache
GitHub and GitLab — works with both gh and glab CLIs
Stays in conversation — after the report opens, ask follow-up questions about any hunk by number

Prerequisites

Install at least one of:

GitHub: GitHub CLI (gh) — brew install gh
GitLab: GitLab CLI (glab) — brew install glab

Also required:

ts-node — npm install -g ts-node typescript (used by the diff parser)

Installation

npx skills add williycole/tell

Detects which agents you have installed (Claude Code, OpenCode, Pi, Cursor, and 50+ more) and wires them up automatically. Restart your agent and /tell is ready.

Manual setup

If you'd rather do it yourself:

git clone https://github.com/williycole/tell.git ~/path/to/tell
ln -s ~/path/to/tell ~/.claude/skills/tell                   # Claude Code
ln -s ~/path/to/tell ~/.config/opencode/skills/tell          # OpenCode
ln -s ~/path/to/tell ~/.pi/agent/skills/tell                 # Pi

Usage

/tell              # auto-detect MR/PR from current branch
/tell !42          # GitLab MR #42
/tell #42          # GitHub PR #42
/tell !42 --learn  # add language idiom annotations
/tell !42 --force  # bypass cache and regenerate
/tell !42 --learn --force

After the HTML report opens in your browser, the agent stays in conversation — you can ask follow-up questions about any hunk by number:

"explain hunk 7 further"
"what's the risk if that pattern in hunk 3 is misused?"
"show me the idiomatic version of file 2, hunk 1"
"which files are most likely to cause a regression?"

Viewer Keyboard Shortcuts

| Key | Action | |-----|--------| | h / ← | Previous file | | l / → | Next file | | j / ↓ | Scroll down | | k / ↑ | Scroll up | | d | Half-page down | | u | Half-page up | | Tab | Toggle focus (diff ↔ explanation) | | c | Open / close coverage drawer | | Esc | Close coverage drawer |

How It Works

Fetch MR/PR — pulls title, description, branch info via gh or glab
Fetch linked issue — extracts requirements from any Closes #N / Refs #N reference
Get the diff — runs git diff origin/<base>...origin/<head> locally and pipes it through tell-parse.ts, which deterministically computes every line number, hunk boundary, and change count — the model never touches these values
Explain each hunk — 1–3 sentences per hunk focused on intent, not syntax
Coverage check — every requirement mapped to covered / partial / missing; unanchored changes flagged as harmless or creep
Render report — injects the JSON into the HTML template, writes to /tmp/tell-N.html, opens in browser

`--learn` Mode

Pass --learn to add language idiom annotations to each hunk:

Language auto-detected from file extension (.ex/.exs → Elixir, .ts/.tsx → TypeScript, .js/.jsx → JavaScript, .css/.scss → CSS)
Each hunk gets an idiom label, a plain-language explanation of why the pattern exists in this language, and an idiomatic flag
When idiomatic: false, a preferred snippet shows the more idiomatic alternative

Useful for onboarding to a new codebase or language.

Report Output

Reports are written to /tmp/tell-<N>.html (or /tmp/tell-<N>-learn.html with --learn). Re-running the same MR/PR opens the cached report instantly. Pass --force to regenerate.

Discovery

Find and explore skills at skills.sh

Local Development

No agent or CLI run needed — just inject a fixture and open in the browser.

Setup

git clone https://github.com/williycole/tell.git
cd tell
npm install

Run the dev viewer

npm run dev
# or
just dev

Reads fixtures/sample.json, injects it into templates/tell-template.html, writes demo/dev.html, and opens it in the browser. Edit the template and re-run to see changes instantly.

Pass a different fixture:

node scripts/dev.js fixtures/my-fixture.json
just dev fixtures/my-fixture.json

Add a fixture

Create fixtures/<name>.json with the Tell JSON schema. Use fixtures/sample.json as a reference — it covers all line types (ctx/add/del), learn blocks, all coverage statuses, and unanchored entries.

Good fixtures to add:

A PR with only deletions
A renamed file
A large hunk that uses the ... N lines omitted placeholder
A --learn report for a non-Elixir language

Run parser tests

npm test

Tests live in tell-parse.test.ts and use the built-in node:test runner (no extra deps).

Test with a real MR before publishing

Symlink your local clone into your agent's skills directory:

ln -sf ~/path/to/tell ~/.claude-work/skills/tell   # Claude Code
ln -sf ~/path/to/tell ~/.pi/agent/skills/tell       # Pi

Restart the agent.
Run /tell !N --force — it will use your local SKILL.md and templates/tell-template.html.
When satisfied, remove the symlink and re-install from npm:
```
npx skills add williycole/tell
```

Contributing

Bug reports and pull requests welcome at github.com/williycole/tell.

License

MIT