Ghost Font Decoder
https://playground.likec4.dev/share/uPAKaklH79/
Give AI agents motion vision.
Decode text hidden inside random-dot “ghost font” videos with Codex,
Claude Code, Claude.ai, or plain Python.
No more ghosting. The message is the motion—and this decoder reads it.
The problem
Ghost-font videos conceal text inside a moving random-dot field. Pause the
video and every frame appears to be uniform noise. The letters emerge only
when their dots move differently from the background, so image-only readers
miss the message entirely.
Ghost Font Decoder analyzes that motion with dense optical flow, reconstructs
the hidden glyphs, and gives the agent both a clean reveal and a heatmap it can
verify.
| Paused frame — looks like noise | Recovered motion mask |
|---|
| |
Why it stands out
- Agent-native — one
ghost-decode skill across Codex, Claude Code, and Claude.ai.
- Actually motion-aware — analyzes movement across frame pairs instead of guessing from a still image.
- Verifiable output — produces both a cleaned binary mask and the raw motion heatmap.
- Works without an agent — the same decoder runs directly from Python.
- OCR is optional — visual recovery still works when Tesseract is unavailable.
- Local by design — decoding runs on the machine executing the skill.
Quick start
Claude Code
Install the plugin, then pass it a video:
/plugin marketplace add haroontrailblazer/ghost-font-decoder
/plugin install ghost-font-decoder@ghost-font-tools
/ghost-decode path/to/ghost-video.mp4
You can also ask naturally:
What does ghost-video.mp4 say?
Codex
Add this repository as a plugin source, install Ghost Font Decoder, start a
new task, and ask:
Use $ghost-decode to tell me what ghost-video.mp4 says.
Codex runs the bundled decoder, inspects the generated mask, displays the
result in the task, and reports the recovered text.
Claude.ai
Build the uploadable skill package:
python claude-ai-skill/build-zip.py
Upload ghost-decode.zip under Settings → Capabilities → Skills, attach a
video, and ask what it says. See the
Claude.ai installation guide for the complete
setup.
Plain Python
pip install -r requirements.txt
python decode.py examples/ghost-message.mp4
The included example decodes to:
Text in the video: HELLO HUMAN
No plugin installation is required. You can also paste
prompts/decode-in-chat.md into a supported chat,
attach the video, and run the same optical-flow workflow.
Proof: decoded by real agents
The screenshots below document the same hidden message—I LOVE YOU—being
recovered in Claude Code, Claude.ai, and Codex. They show the agent invocation,
the reported text, and the generated visual evidence.
1. Claude Code — successful decode
Claude Code ran the decoder across 185 frame pairs, compensated for drift, and
identified the full three-line message.
2. Claude.ai — skill invoked from chat
The uploaded ghost-decode skill accepted the video and returned the hidden
message directly in the conversation.
3. Claude.ai — generated evidence files
Claude.ai returned both outputs used to verify the answer: the cleaned reveal
and the raw motion heatmap.
4. Claude.ai — recovered mask preview
Opening the generated reveal makes the hidden I LOVE YOU message directly
visible.
5. Codex — plugin result rendered in the task
Codex invoked the installed skill, reported the decoded text, rendered the
reveal, and linked both generated outputs.
The screenshots are execution evidence, not mockups. The decoded masks are
generated from motion in the supplied video.
How it works
Video
↓
Dense optical flow between consecutive frames
↓
Median background-motion subtraction
↓
Counter-motion scoring and drift registration
↓
Temporal score accumulation
↓
Thresholding and mask cleanup
↓
Revealed image + heatmap + optional OCR
Under the hood, the decoder:
- Computes dense optical flow between consecutive frames.
- Estimates and subtracts the dominant background movement.
- Scores pixels moving against that background.
- Registers the drifting glyph region with phase correlation.
- Accumulates evidence across time, thresholds it, and cleans the mask.
- Runs optional Tesseract OCR and lets the agent verify the visual result.
Output
Each run writes:
| File | Purpose |
|---|
revealed.png | Clean binary mask for direct visual inspection and OCR |
revealed_heatmap.png | Raw opposition score for faint or partially recovered glyphs |
Useful command-line options:
python decode.py VIDEO \
-o OUT_DIR \
--method farneback \
--stride 2 \
--max-frames 200 \
--no-ocr
Plugin structure
This repository ships native skill packaging for each supported agent:
| Surface | Integration |
|---|
| Claude Code | .claude-plugin/plugin.json, marketplace metadata, and claude-skills/ghost-decode/SKILL.md |
| Claude.ai | Uploadable skill built from claude-ai-skill/ghost-decode/SKILL.md |
| Codex | .codex-plugin/plugin.json, codex-skills/ghost-decode/SKILL.md, and agents/openai.yaml |
| Any supported chat | Portable workflow in prompts/decode-in-chat.md |
| Standalone | decode.py and requirements.txt |
Requirements
- Python 3.8 or newer
- OpenCV
- NumPy
pytesseract for optional OCR
Install Python dependencies:
pip install -r requirements.txt
On Windows, Tesseract can be installed with:
winget install UB-Mannheim.TesseractOCR
The reveal and heatmap are still generated when Tesseract is not installed.
Repository map
ghost-font-decoder/
├── decode.py # Optical-flow decoder
├── examples/ # Reproducible sample video and outputs
├── claude-skills/ # Claude Code skill
├── claude-ai-skill/ # Claude.ai uploadable skill source
├── codex-skills/ # Codex skill and UI metadata
├── commands/ # Claude Code slash command
├── prompts/ # Portable in-chat workflow
└── docs/ # Project page and proof assets
The core insight
Ghost fonts are often presented as text that AI cannot read. The harder truth
is simply that the information is encoded in motion, not in any single
frame. Dense optical flow is designed to measure exactly that signal.
This project packages a proven computer-vision technique as an agent skill, so
the same assistant that receives the video can run the analysis, inspect the
evidence, and answer with the recovered message.
License
Released under the MIT License.
Author
Built by Haroon K M
(@haroontrailblazer).
