Vibrante-Node is a Python node-based visual framework for building modular systems through connected nodes and data flows. It provides an intuitive graph interface where complex logic can be constructed visually by linking nodes together.
The platform focuses on flexibility, extensibility, and developer productivity — making it suitable for visual pipelines, automation workflows, and data-processing graphs across any domain. Node-based systems allow complex operations to be organized as interconnected components rather than traditional linear code structures, improving clarity and scalability in large workflows.
Core capabilities:
- Visual canvas — build workflows by wiring reusable node blocks on a PyQt5 graph canvas; execute via F5, inspect every wire value live
- Extensible node system — drop a
.jsonfile intonodes/and it is registered instantly; no recompile, no plugin manifest - Multi-DCC integration — Houdini (live bridge), Maya (headless), Blender (headless), Prism Pipeline, Deadline
- Automation API — drive the engine programmatically from scripts, CI/CD jobs, or external tools
- AI runtime integration (optional) — connect Claude Desktop, Codex CLI, or Cursor via the built-in MCP server for natural-language orchestration
| Dependency | Version | Notes |
|---|---|---|
| Python | 3.10+ | Required |
| PyQt5 | latest | Required for UI mode |
| pydantic | latest | Required |
| toposort | latest | Required |
| mcp | ≥ 1.0.0 | Required for MCP server mode |
| QScintilla | latest | Optional — full code editor |
git clone https://github.com/KamalTD/Vibrante-Node.git
cd Vibrante-Node
pip install -r requirements.txt
python src/main.pyPre-built Windows executables are available on the Releases page. No Python installation required.
Three installation methods available. See linux/README.md for full instructions.
pip (recommended):
pip install vibrante-node
vibrante-nodeAppImage (self-contained, no Python required):
chmod +x Vibrante-Node-2.5.0-x86_64.AppImage
./Vibrante-Node-2.5.0-x86_64.AppImageUbuntu/Debian .deb:
sudo dpkg -i vibrante-node_2.5.0_amd64.deb
vibrante-nodeWayland note: If the app fails to start, run with
QT_QPA_PLATFORM=xcb vibrante-node.
git clone https://github.com/KamalTD/Vibrante-Node.git
cd Vibrante-Node
pip install -r requirements.txt
python src/main.py- Press F5 to execute the active workflow.
- Hover any wire to inspect the last value that flowed through it.
- Open File → Load Workflow and pick any
.jsonfromworkflows/to explore prebuilt pipelines. - Press Ctrl+Shift+G on any selected group of nodes to collapse them into a reusable Subgraph — the foundation of composable workflow design.
- Open Nodes → Node Builder to create a custom node with a GUI editor.
- Interactive Canvas — pan, zoom, and arrange node graphs on a full-featured Qt canvas
- Live Wire Inspector — hover any connected wire after execution to see the last value that flowed through it
- Type-Coded Ports — ports are colored by data type for instant visual identification
- Mini-map — 200×150 px canvas thumbnail with viewport indicator (Ctrl+M)
- Canvas Search — Ctrl+F filters all nodes by name or node ID; Enter/Shift+Enter cycles matches
- Backdrop / Sticky Notes — annotate and group canvas regions visually
- Async Runtime —
asyncio-basedNetworkExecutorkeeps the UI fully responsive during execution - Exec Flow Pins —
exec_in/exec_outpins control execution order explicitly - Reactive Data Propagation — changing a node value immediately propagates to all connected downstream nodes
- Subgraph / Group Node — collapse any selection into a
GroupNode; double-click to open and edit (Ctrl+Shift+G) - Node Execution Timing — log panel reports elapsed time for each node
| Category | Count | Examples |
|---|---|---|
| Prism Pipeline | 62 | entities, assets, shots, products, USD, configs |
| Maya | 24 | open/save scene, import/export, render, custom Python |
| Blender | 20 | Alembic, FBX, glTF, OBJ, USD, render |
| Houdini (headless) | 17 | open/save HIP, Alembic/FBX import-export, headless executor |
| Houdini AI (MCP) | 23 | scene context, AI planning, transaction, diff, graph builder |
| Generic MCP | 3 | mcp_server_init, mcp_list_tools, mcp_call_tool |
| Network | 1 | http_request — async GET/POST with headers, timeout |
| Control Flow | — | if_condition, for_loop, while_loop, branch |
| Data Structures | — | create_list, create_dictionary, get_dict_value |
| String Utilities | — | string_concat, string_split, string_lowercase |
| Math & Logic | — | math_add, compare, math_abs, logic_and |
| File System | — | file_reader, append_file, create_folder |
- Node Builder — GUI editor: port tables, type dropdowns, automatic Python class generation, bi-directional code sync
- Hot Reload — Ctrl+R rebuilds live canvas instances without restarting
- Python Script Node — inline QScintilla code editor; scripts persisted inside the workflow JSON
- Scripting Console — full API access for programmatic graph manipulation at runtime
- MCP Server Mode — run
scripts/run_vibrante_mcp.py; Claude Desktop, Codex CLI, and Cursor connect via stdio and receive 12 tools for scene inspection, planning, validation, and execution - Safe Transactional Mutations — all operations are validated, recorded, and reversible; high-risk plans require explicit approval before execution
- AI Planning Pipeline — natural language → plan → preview → approved execution; no arbitrary scene mutation
- 200+ Houdini AI Nodes — full semantic assembly pipeline from
hou_mcp_scene_intent_extractthroughhou_mcp_reality_check
- Semantic Scene Intent System — NL prompt →
SceneIntentdataclass via deterministic extraction + optional LLM enhancement; fully typed schema with 14 enum-constrained fields - Scene Planning Runtime —
SceneIntent→ScenePlanwith zones, asset queries, camera targets, and composition rules; all planning-only, no Houdini mutation - Asset Intelligence (Tier 8) — Sketchfab, Polyhaven, and Local Library providers; 6-factor deterministic asset ranking with production memory boost
- Goal Decomposition — "create cinematic explosion scene" automatically expands to 6 ordered workflows and 34 staged operations via deterministic keyword matching
- Workflow Packs — 13 JSON blueprints defining stage-by-stage production sequences for environments, FX, lighting, camera, and rendering
- Cinematic Review Engine — generates specific production critique per stage — not generic success messages
- Runtime Narration —
[Planning],[Execution],[Review]blocks replace opaque "running..." status with specific orchestration reasoning
Open the canvas, drag nodes from the Library panel, connect them, and press F5. Data flows left-to-right through typed data pins; execution order is controlled by exec pins (the white square connectors). Every wire is inspectable after a run — hover to see the last value.
[Source Node] ──data──→ [Transform Node] ──data──→ [Output Node]
exec_out ─────────────→ exec_out ─────────────→ exec_out
Build Once → Reuse Everywhere: group any sub-workflow into a named Subgraph (Ctrl+Shift+G). Subgraphs appear as a single reusable node — duplicate, share, or nest them across projects. Workflow files are plain JSON: diff-friendly and version-control-ready.
Suited for: general automation pipelines, file processing, data transformation, DCC scene setup, Prism Pipeline integration, Deadline submission, API orchestration, and any multi-step task you want to build visually and iterate on interactively.
Workflows scale naturally — a small 3-node graph and a 50-node production pipeline use the same execution model. Group nodes let you collapse subsystems into reusable components, keeping large graphs readable without losing any functionality.
Run scripts/run_vibrante_mcp.py to start a headless MCP server. Claude Desktop, Codex CLI, and Cursor connect via stdio and receive 12 semantic tools covering scene inspection, planning, validation, and transactional Houdini execution — no visual canvas required. See AI Runtime & MCP Integration for setup instructions.
Vibrante-Node/
├── src/
│ ├── core/ # Execution engine, GraphManager, NodeRegistry, WorkflowModel
│ │ ├── executor.py # NetworkExecutor — asyncio coroutine orchestration
│ │ ├── graph.py # GraphManager — DAG, topological sort, cycle detection
│ │ ├── registry.py # NodeRegistry — auto-discovery, hot-reload
│ │ └── models.py # WorkflowModel, PortModel, NodeInstanceModel (Pydantic)
│ ├── ui/ # Qt frontend — canvas, panels, dialogs
│ │ ├── canvas/ # NodeScene, NodeView, MiniMap, CanvasSearchBar
│ │ ├── node_widget.py # Node rendering and reactive propagation
│ │ ├── node_builder.py # GUI node authoring tool
│ │ └── window.py # MainWindow, menus, toolbar, dock layout
│ ├── nodes/
│ │ └── builtins/ # Built-in node implementations (GroupNode, loops, variables)
│ ├── utils/ # Integrations and shared utilities
│ │ ├── hou_bridge.py # Houdini TCP/JSON-RPC client (port 18811)
│ │ ├── prism_core.py # PrismCore singleton and auto-bootstrap
│ │ ├── env_manager.py # Environment variable and path management
│ │ └── qt_compat.py # Qt5/Qt6 compatibility layer
│ ├── runtime/ # Advanced runtime extensions (Tiers 1–6, optional)
│ │ └── ... # MCP server, AI planning, transactions, analytics (40+ modules)
│ └── main.py # Application entry point (UI mode)
│
├── nodes/ # 200+ bundled node definitions (JSON + Python)
├── plugins/ # DCC plugins — houdini/, maya/, blender/
│ └── houdini/
│ ├── v_nodes_houdini/ # Houdini-specific nodes (bridge + AI runtime)
│ └── houdini/scripts/python/ # In-Houdini server + launch scripts
├── scripts/
│ └── run_vibrante_mcp.py # Headless MCP server entry point (advanced)
│
├── workflows/ # General-purpose workflow JSON files
├── vfx_workflows/ # Production VFX pipeline workflows
├── examples/ # Automation scripts and custom node examples
├── docs/ # Generated HTML documentation
├── docs_src/ # Markdown source for documentation
└── tests/ # pytest unit and integration tests
Vibrante-Node is a layered execution platform. The workflow graph drives the execution engine, which runs nodes, which call integrations. The advanced runtime layer is an optional extension used by hou_mcp_* and MCP client nodes.
┌─────────────────────────────────────────────────────────────┐
│ Visual Canvas (src/ui/) │
│ Qt canvas · panels · node widgets · workflow authoring │
├─────────────────────────────────────────────────────────────┤
│ Execution Engine (src/core/) │
│ WorkflowModel → GraphManager (DAG) → NetworkExecutor │
│ asyncio coroutines · topological order · GroupNode recursion│
├─────────────────────────────────────────────────────────────┤
│ Node Library (src/nodes/ + plugins/) │
│ 200+ nodes: General · Houdini · Maya · Blender · Prism · MCP│
├─────────────────────────────────────────────────────────────┤
│ Utils & Integrations (src/utils/) │
│ HouBridge (TCP) · PrismCore · EnvManager · qt_compat │
├ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┤
│ Advanced Runtime Extensions (src/runtime/) ← optional │
│ MCP server · AI planning · transactions · analytics │
│ 40+ modules across Tiers 1–6; no Qt dependency │
└─────────────────────────────────────────────────────────────┘
Execution Engine (src/core/) resolves a topological execution order from the node graph, drives each node's async def execute() via asyncio, and emits Qt signals for live wire inspection and log output. GroupNode execution recurses into embedded sub-workflows.
Node Library (src/nodes/) manages node definitions (JSON + compiled Python), the NodeRegistry (auto-discovery, hot-reload), and the BaseNode contract. Adding a node requires exactly one .json file — drop it in nodes/ and it registers automatically.
Visual Canvas (src/ui/) is a QGraphicsScene/QGraphicsView pair with thread-safe reactive propagation, mini-map, canvas search, live wire inspector, and the Node Builder authoring tool.
Advanced Runtime Extensions (src/runtime/) is an optional standalone Python module — MCP server, AI planning, transaction management, validation, and analytics (Tiers 1–6). It has no Qt dependency and can run headlessly. Used by hou_mcp_* nodes and the scripts/run_vibrante_mcp.py entry point.
A full Houdini plugin ships in plugins/houdini/. It starts a JSON-RPC server (vibrante_hou_server.py) inside a live Houdini session. The HouBridge client communicates over TCP with TCP_NODELAY and 30-second timeout, automatic reconnect, and per-call thread locking.
v2.4.0 additions: get_selection() (selected node paths), network_summary(path) (children with type+category in one round-trip). v2.5.0 additions: VIBRANTE_MEGASCANS_LIBRARY path checked in startup diagnostics; vibrante_node.json expanded with 12 acquisition and storage env vars.
Setup: configure VIBRANTE_NODE_APP in plugins/houdini/vibrante_node.json, install the package in Houdini, then launch from the Vibrante-Node shelf or menu.
maya_action_* nodes append operation dictionaries to a list; a maya_headless node executes the full list in a batch Maya session. Supports open/save, import/export (Alembic, FBX), render, MEL/Python, node creation.
Same action-list pattern as Maya. blender_action_* nodes + blender_headless executor. Supports Alembic, FBX, glTF, OBJ, USD, render.
62 nodes covering the full Prism v2 API. PrismCore bootstraps automatically before graph execution — place a prism_core_init node anywhere in the graph; no wiring required.
vfx_workflows/04_deadline_render_pipeline.json demonstrates render farm submission integrated with Prism asset management.
Vibrante-Node can run as a headless MCP server, letting Claude Desktop, Codex CLI, and Cursor plan, validate, and execute Houdini operations through 12 structured tools. No Qt or display server required.
Start the MCP server:
pip install "mcp>=1.0.0" pydantic toposort
python scripts/run_vibrante_mcp.pyOn Windows, use the full interpreter path (e.g. C:/Python311/python.exe) and forward slashes in all paths below.
Claude Code (CLI / VS Code extension):
claude mcp add-json vibrante '{
"command": "python",
"args": ["/path/to/Vibrante-Node/scripts/run_vibrante_mcp.py"],
"env": { "VIBRANTE_HOU_PORT": "18811" }
}' --scope userThis registers the server in ~/.claude.json (user scope — available in every project). For a per-project setup, put the same mcpServers block in a .mcp.json file at the repository root instead. Verify with claude mcp get vibrante, or /mcp inside a session.
Note: Claude Code does not read
mcpServersfrom~/.claude/settings.json— a server defined there is silently ignored. Useclaude mcp add/.mcp.jsonas shown above.
Claude Desktop — Settings → Developer → Edit Config, or edit the file directly (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"vibrante": {
"command": "python",
"args": ["/path/to/Vibrante-Node/scripts/run_vibrante_mcp.py"],
"env": { "VIBRANTE_HOU_PORT": "18811" }
}
}
}Codex CLI (~/.codex/config.toml):
[mcp_servers.vibrante]
command = "python"
args = ["/path/to/Vibrante-Node/scripts/run_vibrante_mcp.py"]Cursor (.cursor/mcp.json in the workspace root, or ~/.cursor/mcp.json globally) — same JSON block as Claude Desktop.
Optional environment variables (set in the server's env block):
| Variable | Purpose |
|---|---|
VIBRANTE_HOU_PORT |
Port of the live Houdini bridge (default 18811) |
VIBRANTE_NODE_APP |
Absolute path to the Vibrante-Node app root |
VIBRANTE_MEGASCANS_TOKEN |
Megascans / Fab API token — enables online asset acquisition (all tools stay offline-safe if unset) |
VIBRANTE_ASSET_CACHE |
Local asset cache directory used by the download pipeline |
VIBRANTE_MEGASCANS_LIBRARY / VIBRANTE_FAB_LIBRARY |
Paths to your local Megascans / Fab libraries for scanning and indexing |
The server exposes 12 semantic tools across four categories — Runtime, Knowledge, Planning, and Execution. Planning and knowledge tools work without Houdini; only execute_workflow_transaction touches the scene, and only after validation passes. All 40+ runtime modules run headlessly without Qt — CI/CD pipelines can import src.runtime directly.
For the full tool reference, Codex CLI / Cursor configuration, and safety model, see Getting Started § 11.
A simple workflow that requires no integrations. Runs on any machine.
file_reader ── read source file
↓
python_script ── parse and transform data
↓
if_condition ── check record_count > 0
↓ (true) ↓ (false)
append_file console_print "no records"
↓
console_print ── "report saved"
Load workflows/file_processing_example.json and press F5.
prism_core_init ── initialise project management
↓
prism_get_assets ── list assets for the current shot
↓
for_loop ── iterate each asset
↓
hou_create_geo ── build geo container in /obj
↓
hou_import_alembic ── import Alembic cache
↓
console_print ── log result per asset
Uses the AI planning pipeline inside the visual canvas.
prism_core_init
↓
hou_mcp_scene_context ── read current Houdini state
↓
hou_mcp_ai_plan ── "build a cinematic pyro explosion at /obj/geo1"
↓
hou_mcp_ai_preview ── validate risk, check dependencies
↓
if_condition ── check risk_level == "low"
↓ (true)
hou_mcp_ai_execute ── execute with approver="td_lead"
↓
hou_mcp_ai_review ── verify intent matched execution
↓
console_print ── log outcome
Without the visual canvas — Claude Desktop connected to the MCP server.
initialize_runtime_context ── bootstrap and get system prompt
↓
query_scene_context ── read current Houdini scene state
↓
plan_scene("build a pyro sim") ── natural language → validated plan
↓
preview_execution(operations) ── validate risk before touching the scene
↓
execute_workflow_transaction ── commit; auto-rollback on failure
↓
review_execution(plan, result) ── verify intent matched execution
Every node is a Python class paired with a JSON definition. The class inherits BaseNode and implements an async execute(inputs) coroutine.
from src.nodes.base import BaseNode
class My_Node(BaseNode):
name = "my_node"
def __init__(self):
super().__init__() # adds exec_in and exec_out automatically
# [AUTO-GENERATED-PORTS-START]
self.add_input("text", "string", widget_type="text", default="hello")
self.add_input("repeat", "int", widget_type="int", default=1)
self.add_output("result", "string")
# [AUTO-GENERATED-PORTS-END]
async def execute(self, inputs):
text = inputs.get("text", "")
n = int(inputs.get("repeat", 1))
return {
"result": (text + " ") * n,
"exec_out": True,
}
def register_node():
return My_NodeFor the complete authoring reference, including Houdini bridge usage, headless action patterns, and Prism integration, see NODE_BUILDER_API.md.
Houdini nodes not appearing in the Library
Ensure v_nodes_dir points to plugins/houdini/v_nodes_houdini/
Set it in Edit → Preferences → Application Paths (requires restart)
AppImage fails to start on Linux
QT_QPA_PLATFORM=xcb ./Vibrante-Node-2.5.0-x86_64.AppImageNode Builder corrupts exec ports on edit
This was fixed in v2.3.0. Update to the latest release.
MCP server won't start (Advanced)
# Verify mcp is installed
python -c "import mcp; print(mcp.__version__)"
# If missing: pip install "mcp>=1.0.0"query_scene_context returns "bridge not available" (Advanced)
1. Open Houdini with the Vibrante-Node plugin installed
2. Click Vibrante-Node → Launch Vibrante-Node from the Houdini menu bar
3. Check VIBRANTE_HOU_PORT matches the port shown in the Houdini Python console
execute_workflow_transaction returns status: "pending_approval" (Advanced)
The plan has requires_approval=True (high risk or delete_node ops).
Pass approver="your_name" to authorize execution.
| Resource | Description |
|---|---|
| User Guide | Interface, canvas, execution, keyboard shortcuts |
| Node Builder API | Creating and distributing custom nodes |
| Automation & Scripting API | Scripting Console and programmatic graph control |
| Developer Guide | Architecture, engine internals, runtime layer |
| Technical Reference | Complete feature and API reference |
| Portal Docs | Full HTML documentation portal |
| Changelog | Version history and migration notes |
Release Notes:
| Version | Type | Highlights |
|---|---|---|
| v2.5.0 | Minor | Semantic Scene Intent System; 200+ Houdini AI nodes; full environment assembly pipeline (Tiers 8–15.0+); networkx dependency; 250+ new tests |
| v2.4.0 | Minor | 26 new nodes (3 generic MCP client + 23 Houdini AI); runtime extensions layer (Tiers 1–6): MCP server, AI planning, transactions; node ID cleanup; 3 bug fixes |
| v2.3.0 | Minor | HTTP Request node; Authenticode signing tools; Node Builder fixes; canvas drag-trail fix |
| v2.2.1 | Patch | About dialog crash fix; LICENSE bundled in exe |
| v2.2.0 | Minor | Settings dialog; EnvManager; reactive propagation fix; 10 new website examples |
| v2.1.1 | Patch | Scripting Console theme fix; Windows VERSIONINFO in exe |
| v2.1.0 | Minor | Unsaved-changes detection; type-mismatch warning; F5 shortcut fix |
| v2.0.0 | Major | GroupNode; mini-map; canvas search; autosave; wire inspector; execution timing |
| v1.8.x | — | QScintilla editor; hot-reload; init-first ordering; Houdini bridge hardening |
Contributions are welcome. The project is under active development; new integrations, nodes, and runtime improvements are ongoing priorities.
- Fork the repository and create a feature branch from
main - Run the test suite before submitting:
pytest tests/ - Follow the node authoring conventions documented in NODE_BUILDER_API.md
- Open a pull request with a concise description of the change and motivation
Bug reports and feature requests: GitHub Issues
Questions and general discussion: GitHub Discussions
By contributing you agree to the terms of the Contributor License Agreement.
Vibrante-Node uses an open-core hybrid licensing model.
| Component | License |
|---|---|
| Core Runtime | AGPLv3 |
| SDK / Public API | MIT |
| Documentation & Examples | CC BY 4.0 |
| Official Plugins & Nodes | Commercial |
| Enterprise Integrations | Commercial |
Free for individuals, students, education, and open productions.
Commercial studio deployment requires a commercial license.
- LICENSE — AGPLv3 runtime + MIT SDK + CC BY 4.0 docs
- COMMERCIAL_LICENSE.md — Studio, SaaS, and enterprise terms
- TRADEMARK_POLICY.md — Vibrante-Node branding guidelines
- CLA.md — Contributor License Agreement
Licensing inquiries: contact@vibrante-node.com
© 2024–2026 Mahmoud Kamal (KamalTD). All rights reserved.