Skip to content
Back to search

codeparable

SkillWorks with Claude CodeGitHub

Explain any codebase with hand-drawn parables that mean something: one drawing per real component, counts from real data, labels in any language (RTL too), 9:16 scenes and a captioned reel. A skill for Claude Code and coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ssepehrnoush--codeparable/badge.svg)](/listings/ssepehrnoush--codeparable)

HTML

<a href="/listings/ssepehrnoush--codeparable"><img src="/api/listings/ssepehrnoush--codeparable/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

git clone https://github.com/ssepehrnoush/codeparable.git
cp -R codeparable/skills/codeparable ~/.claude/skills/
pip install pillow

Windows (PowerShell):

git clone https://github.com/ssepehrnoush/codeparable.git; Copy-Item -Recurse codeparable\skills\codeparable "$HOME\.claude\skills\"; pip install pillow

Then, in your project: *"Use codeparable to explain how a request moves through this app."* With other agents, point them at `skills/codeparable/SKILL.md`.

Drawing sprites needs an image API key: `OPENAI_API_KEY`, or any OpenAI-compatible endpoint through `OPENAI_BASE_URL` and `IMAGE_MODEL`. Rendering needs Chrome or Edge. The reel needs Node (`npx hyperframes`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 97 lines
  1. # codeparable
  2. **Explain any codebase with drawings that mean something.**
  3. A skill for Claude Code and other coding agents. It reads your code and its real numbers, then draws a few hand-made parables of how the system works: 9:16 scenes, plus a captioned vertical video if you want one.
  4. ![License: MIT](https://img.shields.io/badge/license-MIT-blue) ![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue) ![Dependencies: Pillow only](https://img.shields.io/badge/dependencies-Pillow%20only-green) ![Languages: any, RTL too](https://img.shields.io/badge/labels-any%20language%2C%20RTL%20too-orange)
  5. [فارسی](README.fa.md)
  6. ![Five scenes explaining full-stack-fastapi-template](docs/scenes-en.jpg)
  7. Every drawing stands for one real thing. The gatehouse is the Traefik proxy. The sealed ticket is the JWT, valid 8 days. The 23 doors are the template's 23 real routes: 6 open, 11 that need the ticket, 6 for superusers only. Nobody guessed those numbers; they were counted from the code.
  8. ![23 doors appearing, one per real route](docs/demo-doors.gif)
  9. ## Why another code explainer
  10. Code maps already exist, and some are very good (see the comparison below). They show **structure**: files, imports, modules. When you have lost track of a system you built, structure is rarely what you are missing. You are missing the **mechanism**: what happens to one request, where things leak, which knob changes what. codeparable is built for that:
  11. - **Meaningful elements only.** A meaning contract (`sprites.json`) gives every drawing a real counterpart. Decorative drawings are not allowed.
  12. - **Real numbers, drawn exactly.** Counts are drawn as that many copies, widths and fill levels are proportional, and every number keeps a `sources` line saying where it was measured.
  13. - **Text that is always right.** Image models garble letters, especially in Persian and Arabic. Here the model draws objects only. Every label is real typed text, so it works in any language, right-to-left included.
  14. - **From stills to a reel.** The same scenes become a vertical, captioned, silent video (via [HyperFrames](https://hyperframes.studio)), ready for your own voice-over.
  15. ## Install
  16. ```bash
  17. git clone https://github.com/ssepehrnoush/codeparable.git
  18. cp -R codeparable/skills/codeparable ~/.claude/skills/
  19. pip install pillow
  20. ```
  21. Windows (PowerShell):
  22. ```powershell
  23. git clone https://github.com/ssepehrnoush/codeparable.git; Copy-Item -Recurse codeparable\skills\codeparable "$HOME\.claude\skills\"; pip install pillow
  24. ```
  25. Then, in your project: *"Use codeparable to explain how a request moves through this app."* With other agents, point them at `skills/codeparable/SKILL.md`.
  26. Drawing sprites needs an image API key: `OPENAI_API_KEY`, or any OpenAI-compatible endpoint through `OPENAI_BASE_URL` and `IMAGE_MODEL`. Rendering needs Chrome or Edge. The reel needs Node (`npx hyperframes`).
  27. ## How it works
  28. ```
  29. sprites.json what each drawing means -> parable.py sprites (one isolated object per call)
  30. scenes.json layout, data, sources -> parable.py check (the contract must hold)
  31. -> parable.py render (1080x1920 PNGs + meaning table)
  32. narration lines -> parable.py reel (HyperFrames project, then render)
  33. ```
  34. The example in [`examples/fastapi-template`](examples/fastapi-template) has both files in English and Persian, with every number's source.
  35. ## What it reads and what it touches
  36. | | |
  37. |---|---|
  38. | Reads | your code, and whatever counts you or your agent measure (logs, a read-only query, config names) |
  39. | Sends out | one prompt per drawing to the image API you configure; no code is sent there, only object descriptions |
  40. | Writes | only inside the project folder you give it: `sprites/`, `out/`, `reel/` |
  41. | Never | edits your code, deploys, or uploads anything anywhere |
  42. ## Keep the parables honest in CI
  43. ```yaml
  44. - run: pip install pillow
  45. - run: python skills/codeparable/scripts/parable.py check docs/parables # fails on a drawing without a meaning or a number without a source
  46. ```
  47. ## What it deliberately does not do
  48. - **It does not invent numbers.** If nobody measured it, the scene says so or leaves it out.
  49. - **It does not draw diagrams of every file.** For that, use a code map (below). A parable shows one mechanism at a time.
  50. - **It does not let the image model write.** No letters, numbers or logos in drawings, ever.
  51. - **It does not record a voice.** The reel is silent on purpose, with a timed script, so you can narrate it yourself.
  52. - **It does not guarantee the same drawing twice.** Sprites are generated; keep the PNGs you like in your repo.
  53. ## Compared with tools we actually ran
  54. We ran these on the same private two-repo project before building this (November 2026):
  55. | Tool | Good at | Missing for this job |
  56. |---|---|---|
  57. | [Floorplan](https://github.com/haydenschmitty/floorplan) | zoomable plain-English map of many repos | no counts from data, no decision rules or costs; edge weight is call sites |
  58. | [Understand-Anything](https://github.com/Egonex-AI/Understand-Anything) | rich knowledge graph, tours, Persian summaries | edge weights fixed by type, no live numbers, needs a local server to view |
  59. | [CodeBoarding](https://github.com/CodeBoarding/CodeBoarding) | component diagrams with any LLM | generic descriptions; viewer is a web app |
  60. | [GitDiagram](https://github.com/ahmedkhaleel2004/gitdiagram), [DeepWiki](https://deepwiki.com) | instant diagram or wiki of a public repo | one level, hosted (not for private code), no numbers |
  61. codeparable does not replace a code map. Use one to find files, and use codeparable to explain how the system behaves.
  62. ## Credits
  63. The hand-drawn, one-object-per-idea style is inspired by [ian-xiaohei-illustrations](https://github.com/helloianneo/ian-xiaohei-illustrations) (MIT). The Persian and Latin font is [Vazirmatn](https://github.com/rastikerdar/vazirmatn) (SIL OFL 1.1). The demo explains [full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) (MIT). Details are in [NOTICE.md](NOTICE.md).
  64. ## License
  65. MIT, see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.