Deterministic Visualizations & Explanations for Blackbox Code
Copilot writes. Cursor generates. Claude produces. Legacy code just exists. TrueFlow reveals what it all actually does.
Two types of code are equally terrifying:
-
AI-generated code — Millions of lines pasted into production daily. The code works (mostly). But do you truly understand what it does? When you ask an LLM to explain its own code, trace methods, produce sequence diagram (not MCP based), you get probabilistic guesses dressed as confident explanations.
-
Legacy codebases — That 10-year-old monolith. The original authors left years ago. Documentation is a myth. Tribal knowledge lives in Slack threads from 2019. You're afraid to touch it because nobody knows what it actually does anymore.
Both share the same fundamental problem: blackbox code.
Whether it's Claude's 500-line async handler or that ancient Django app with 47 circular imports—you're navigating blind.
You're debugging code without ground truth.
We built TrueFlow because we were tired of:
| Pain Point | Reality |
|---|---|
| Writing loggers for every method | Just to trace a single flow |
| Paid sequence diagram tools | Outdated, limited, no animations |
| Static analysis OR runtime tracing | Never both. Always incomplete. |
| Multiple plugins duct-taped together | Coverage here, diagrams there, traces somewhere else |
| LLM explanations that sound right | But aren't grounded in actual execution |
| Legacy code with zero documentation | Original authors long gone, tribal knowledge lost |
| "Just read the code" | 500K lines across 12 services? Good luck. |
| Onboarding takes months | Because nobody can explain how it actually works |
TrueFlow is the answer: One tool. Zero code changes. Deterministic truth.
┌─────────────────────────────────────────────────────────────────────────┐
│ TrueFlow │
│ │
│ AST Static Analysis ──────┬────── Runtime Tracing │
│ │ │
│ ▼ │
│ ┌─────────────────┐ │
│ │ Ground Truth │ │
│ └─────────────────┘ │
│ │ │
│ ┌────────────────────┼────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Mermaid │ │ Manim │ │ Local LLM │ │
│ │ Diagrams │ │ Animations │ │ Summaries │ │
│ └──────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
TrueFlow intercepts actual execution, captures real data flow, and transforms it into visualizations and explanations grounded in what happened—not what an LLM thinks might have happened.
No SDK. No decorators. No logging boilerplate. No code changes whatsoever.
TRUEFLOW_ENABLED=1 python your_script.py
# That's it. Traces appear automatically.Works with Python 2.7+ and 3.x. Universal compatibility.
Real method calls. Real arguments. Real return values. Exported to formats you already use.
11+ Export Formats: PlantUML • Mermaid • D2 • JSON • Markdown • ASCII • Flamegraph • LLM-ready summaries
sequenceDiagram
participant Client
participant API
participant Database
Client->>API: POST /users {"name": "Alice"}
API->>Database: INSERT INTO users...
Database-->>API: user_id: 42
API-->>Client: 201 Created
This diagram was generated from actual execution—not imagination.
Static diagrams are dead. Watch your code execute.
Powered by Manim (the engine behind 3Blue1Brown), TrueFlow generates:
- Animated architecture diagrams — Components light up as they're invoked
- Data flow cinematics — Watch data transform as it moves through your system
- Execution narratives — Function calls choreographed as visual sequences
python ultimate_architecture_viz.py --trace traces/session_001.json
Screen.Recording.2025-11-29.215801_1_1.mp4
Finally understand that 500-line async task queue Claude generated.
Static analysis tells you what could run. Runtime tracing tells you what did run.
TrueFlow combines both:
- AST-based static analysis — Map all possible paths
- Runtime data coverage — Record which paths executed with which data
- Dead code detection — Identify unreachable code with certainty
- Semantic coverage — Not just line coverage, but meaning coverage
Every method call. Timed. Automatically.
No decorators. No @profile. No manual instrumentation. TrueFlow injects timing at runtime and shows you exactly where time is spent.
Export traced execution to a lightweight local LLM for deterministic summarization.
- Private — Runs on your machine, on CPU (llama.cpp)
- Fast — 2B parameters, ~15-25 seconds per explanation
- Grounded — Explains what actually happened, not what might have happened
- No cloud — Your code never leaves your machine
TrueFlow automatically recognizes and visualizes:
| Category | Protocols |
|---|---|
| Data | SQL, GraphQL, gRPC, REST |
| Messaging | Kafka, Redis, MQTT, RabbitMQ |
| Realtime | WebSocket, WebRTC, SSE |
| AI/Agents | MCP, A2A, LangChain, AutoGen |
Intelligent detection for modern and legacy stacks:
Modern:
- Web: FastAPI, Flask, Django, Starlette
- AI/ML: PyTorch, TensorFlow, LangChain, AutoGen, CrewAI
- Data: Pandas, NumPy, SQLAlchemy, Polars
Legacy-Friendly:
- Classic Web: Django 1.x, Flask 0.x, Tornado, CherryPy
- Enterprise: Celery, RabbitMQ consumers, legacy SOAP clients
- Monoliths: Works on any Python codebase, no matter how tangled
git clone https://github.com/trueflow/TrueFlow.git
cd TrueFlow
# Build everything (installs Python deps + builds plugins)
build_all.bat # Windows
./build_all.sh # Linux/Mac
# Or build just the PyCharm plugin
./gradlew buildPlugin
# Install via: Settings → Plugins → Install from Disk
# Select: build/distributions/SequenceDiagramPython-*.zip10-tab interface. Real-time visualization. One-click project integration.
cd TrueFlow/vscode-extension
npm install
npm run compile
npx vsce package
# Install the extension
code --install-extension trueflow-0.1.0.vsix
cd TrueFlow
pip install -e .
# Trace any Python script
PYCHARM_PLUGIN_TRACE_ENABLED=1 python your_script.py
# Find traces in ./traces/
ls traces/
# session_2024_01_15_143052.jsoncd TrueFlow/manim_visualizer
pip install -r requirements.txt
# Create video from trace
python ultimate_architecture_viz.py --trace traces/session_*.json
# Output: media/videos/execution_flow.mp4# Windows - builds PyCharm plugin, VS Code extension, installs Python deps
build_all.bat
# With quick tests
build_all.bat --test
# Skip Python dependency installation
build_all.bat --skip-python
# Linux/Mac
./build_all.sh
./build_all.sh --test# Windows
run_all_tests.bat
# Linux/Mac
./run_all_tests.sh| Suite | Tests | Description |
|---|---|---|
| Manim Unit Tests | 70 | Frame bounds, animation pacing, base visualizer |
| Visual Regression | 15 | Video quality, coordinate tracking |
| E2E Regression | 22 | Full workflow validation |
| Runtime Instrumentor | 18 | Core tracing functionality |
| Error Handling & E2E | 21 | Crash prevention, graceful degradation |
| Protocol Detection | 4 | SQL, WebSocket, gRPC detection |
| Manim Integration | 7 | Plugin integration tests |
| New Visualizers | 6 | Extended visualizer tests |
| TOTAL | ~163 | Full regression suite |
./gradlew runQuickTests # Fast unit tests (~10s)
./gradlew runFastTests # All except slow (~60s)
./gradlew runRegressionTests # Full suite (~3-5 min)
./gradlew runIntegrationTests # Integration only
./gradlew generateCoverageReport # HTML coverage report# Set PYTHONPATH first
export PYTHONPATH="$PWD/src/main/resources/runtime_injector:$PWD/src/main/resources:$PWD:$PWD/manim_visualizer"
# Run specific test files
python -m pytest tests/test_runtime_instrumentor_unit.py -v
python -m pytest tests/test_error_handling.py -v
python -m pytest manim_visualizer/tests/test_frame_bounds_validation.py -v┌──────────────────────────────────────────────────────────────────┐
│ Your Python App Starts │
│ │ │
│ ▼ │
│ TrueFlow Injector Loads (via PYTHONPATH/sitecustomize.py) │
│ │ │
│ ▼ │
│ sys.settrace() Hooks Every Function Call │
│ │ │
│ ▼ │
│ Events Stream to Socket (port 5678) │
│ │ │
│ ├──────────────────┬──────────────────┐ │
│ ▼ ▼ ▼ │
│ IDE Plugin Manim Renderer Local LLM │
│ (Real-time) (Animations) (Explanations) │
└──────────────────────────────────────────────────────────────────┘
Performance overhead: < 2.5% (typically 0.1–0.5ms per request)
TrueFlow/
├── src/main/resources/
│ └── runtime_injector/ # Zero-code Python instrumentation
│ ├── python_runtime_instrumentor.py # sys.settrace() hooks
│ ├── sitecustomize.py # Auto-loader via PYTHONPATH
│ └── local_llm_server.py # Local LLM integration
├── manim_visualizer/ # 3D animated execution videos
│ ├── ultimate_architecture_viz.py # Main visualizer
│ ├── requirements.txt # Manim dependencies
│ └── tests/ # Visualization tests
├── src/main/kotlin/ # PyCharm plugin (Kotlin)
├── vscode-extension/ # VS Code extension (TypeScript)
├── tests/ # Runtime injector tests
├── build_all.bat # Build all components
├── run_all_tests.bat # Run full test suite
└── setup.py # Python package setup
| Variable | Description | Default |
|---|---|---|
PYCHARM_PLUGIN_TRACE_ENABLED |
Enable tracing | 0 |
CRAWL4AI_TRACE_DIR |
Output directory | ./traces |
PYTHONPATH |
Must include .pycharm_plugin |
- |
CRAWL4AI_TRACE_MODULES |
Modules to trace (empty=all) | - |
PYCHARM_PLUGIN_SOCKET_SAMPLE_RATE |
Sample 1 in N events | 10 |
TRUEFLOW_SOCKET_PORT |
Trace server port | 5678 |
| Guarantee | Implementation |
|---|---|
| Memory Safety | Hard limit: 100,000 calls max |
| Graceful Degradation | TrueFlow failures never crash your app |
| Zero Impact | If tracing fails, your code runs normally |
| Test Coverage | 163 tests passing |
Your production code is sacred. TrueFlow observes without interfering.
You: "Claude, write me an async task queue with retries"
Claude: *generates 500 lines of asyncio spaghetti*
You: *runs TrueFlow*
TrueFlow: *shows exactly how tasks flow, retry, and fail*
New Dev: "How does the payment flow work?"
Team Lead: "Uh... check the PaymentService? Or maybe OrderProcessor?
Actually, ask Dave. Oh wait, Dave left in 2021."
TrueFlow: *traces actual checkout → shows 47 classes, 3 services,
2 message queues, and that weird singleton everyone forgot about*
New engineers run TrueFlow on key user journeys. Within hours, they have:
- Animated architecture diagrams of real execution paths
- Sequence diagrams showing actual class interactions
- Data flow visualizations with real payloads
- Auto-generated documentation grounded in truth
No more "shadow a senior dev for 3 months."
Before touching that 10-year-old module:
- Run TrueFlow on production traffic patterns
- Capture actual execution paths and dependencies
- Refactor with confidence—you know what really gets called
- Compare before/after traces to verify behavior preservation
- PyCharm plugin (10-tab interface)
- VS Code extension
- Mermaid/PlantUML/D2 export
- Manim visualizations
- Local LLM explanations (Qwen 2B via llama.cpp)
- 163 regression tests
- Browser-based viewer
- Java/TypeScript support
- Distributed tracing correlation
We welcome contributions. See CONTRIBUTING.md.
Ways to help:
- Report bugs and request features
- Submit pull requests
- Improve documentation
- Create visualization themes
- Build additional IDE extensions
MIT License — See LICENSE
Two forces are making code harder to understand:
- LLMs generate code at superhuman speed
- Legacy systems accumulate complexity over decades
Both create blackbox code. Understanding it at human speed is the bottleneck.
TrueFlow closes the gap.
No more hallucinated explanations. No more guesswork diagrams. No more "ask Dave, oh wait Dave left." No more "I think this is what it does."
Just deterministic truth about what your code actually does at runtime.
TrueFlow
Deterministic truth for blackbox code—whether AI wrote it yesterday or humans wrote it a decade ago.
Get Started •
Report Bug •
Discuss