codeparable
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.
Badge for your README
Markdown
[](/listings/ssepehrnoush--codeparable)HTML
<a href="/listings/ssepehrnoush--codeparable"><img src="/api/listings/ssepehrnoush--codeparable/badge.svg" alt="findsafeskills safety rating" /></a>Install
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
- # codeparable
- **Explain any codebase with drawings that mean something.**
- 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.
-    
- [فارسی](README.fa.md)
- 
- 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.
- 
- ## Why another code explainer
- 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:
- - **Meaningful elements only.** A meaning contract (`sprites.json`) gives every drawing a real counterpart. Decorative drawings are not allowed.
- - **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.
- - **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.
- - **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.
- ## Install
- ```bash
- git clone https://github.com/ssepehrnoush/codeparable.git
- cp -R codeparable/skills/codeparable ~/.claude/skills/
- pip install pillow
- ```
- Windows (PowerShell):
- ```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`).
- ## How it works
- ```
- sprites.json what each drawing means -> parable.py sprites (one isolated object per call)
- scenes.json layout, data, sources -> parable.py check (the contract must hold)
- -> parable.py render (1080x1920 PNGs + meaning table)
- narration lines -> parable.py reel (HyperFrames project, then render)
- ```
- The example in [`examples/fastapi-template`](examples/fastapi-template) has both files in English and Persian, with every number's source.
- ## What it reads and what it touches
- | | |
- |---|---|
- | Reads | your code, and whatever counts you or your agent measure (logs, a read-only query, config names) |
- | Sends out | one prompt per drawing to the image API you configure; no code is sent there, only object descriptions |
- | Writes | only inside the project folder you give it: `sprites/`, `out/`, `reel/` |
- | Never | edits your code, deploys, or uploads anything anywhere |
- ## Keep the parables honest in CI
- ```yaml
- - run: pip install pillow
- - run: python skills/codeparable/scripts/parable.py check docs/parables # fails on a drawing without a meaning or a number without a source
- ```
- ## What it deliberately does not do
- - **It does not invent numbers.** If nobody measured it, the scene says so or leaves it out.
- - **It does not draw diagrams of every file.** For that, use a code map (below). A parable shows one mechanism at a time.
- - **It does not let the image model write.** No letters, numbers or logos in drawings, ever.
- - **It does not record a voice.** The reel is silent on purpose, with a timed script, so you can narrate it yourself.
- - **It does not guarantee the same drawing twice.** Sprites are generated; keep the PNGs you like in your repo.
- ## Compared with tools we actually ran
- We ran these on the same private two-repo project before building this (November 2026):
- | Tool | Good at | Missing for this job |
- |---|---|---|
- | [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 |
- | [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 |
- | [CodeBoarding](https://github.com/CodeBoarding/CodeBoarding) | component diagrams with any LLM | generic descriptions; viewer is a web app |
- | [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 |
- codeparable does not replace a code map. Use one to find files, and use codeparable to explain how the system behaves.
- ## Credits
- 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).
- ## License
- MIT, see [LICENSE](LICENSE).
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.