NebulaFlow Documentation
Welcome to the NebulaFlow documentation! This is the main entry point for all documentation related to the NebulaFlow VS Code extension.
What is NebulaFlow?
NebulaFlow is a VS Code extension that enables you to design and run LLM+CLI workflows as visual node graphs. It provides an intuitive webview interface where you can connect nodes representing different operations and execute them in sequence.
Key Features
- Visual Workflow Design: Drag and drop nodes to create complex workflows
- LLM Integration: Connect to LLM nodes for intelligent processing using Amp SDK and OpenRouter SDK
- CLI Execution: Run shell commands as part of your workflow
- Conditional Logic: Add decision points and branching logic with If/Else nodes
- Loop Support: Create iterative workflows for repetitive tasks with Loop Start and Loop End nodes
- Real-time Execution: Monitor workflow execution with streaming events
- Approval System: Control when sensitive operations run (CLI nodes require approval)
- Subflows: Create reusable workflow components
- Variables & Accumulators: Store and manipulate data across workflow execution
Architecture
NebulaFlow consists of two main components:
- VS Code Extension: Runs in VS Code, manages the webview interface and workflow execution
- Webview UI: React-based interface using React Flow for visual graph editing
The extension uses the Amp SDK and OpenRouter SDK for LLM operations and executes CLI commands through the Node.js child_process API. Execution is orchestrated in the extension with streaming output, approval system, and real-time event handling.
Available Nodes
NebulaFlow provides the following node types:
Agent Nodes
- LLM Node: Interact with Large Language Models (requires AMP_API_KEY)
Shell Nodes
- CLI Node: Execute shell commands (requires approval for execution)
Text Nodes
- Text Node: Input text data (formerly “Input Node”)
- Accumulator Node: Accumulate text across multiple inputs
- Variable Node: Store and reference variables
Logic Nodes
- If/Else Node: Branch workflow based on conditions
- Loop Start Node: Begin a loop iteration
- Loop End Node: End a loop iteration
Preview Node
- Preview Node: Display data for debugging
Subflow Nodes
- Subflow Node: Embed a reusable subflow
- Subflow Input Node: Define input ports for subflows
- Subflow Output Node: Define output ports for subflows
Execution Model
NebulaFlow workflows execute with the following characteristics:
- Streaming Output: Real-time streaming of LLM responses and CLI output
- Approval System: CLI nodes require user approval before execution
- Parallel Execution: Nodes execute in parallel when dependencies are satisfied
- Pause/Resume: Workflows can be paused and resumed from any node
- Error Handling: Graceful error handling with detailed error messages
Protocol
The extension and webview communicate using a custom workflow message protocol defined in workflow/Core/Contracts/Protocol.ts. Message types include:
- Commands:
execute_workflow, abort_workflow, pause_workflow, node_approved, node_rejected
- Events:
execution_started, execution_completed, node_execution_status, node_output_chunk, node_assistant_content
- Data Transfer:
workflow_loaded, workflow_saved, provide_custom_nodes
Configuration
Environment Variables
- AMP_API_KEY: Required for LLM node execution (Amp SDK)
- OPENROUTER_API_KEY: Optional for OpenRouter SDK integration
VS Code Settings
nebulaFlow.storageScope: Choose between user or workspace storagenebulaFlow.globalStoragePath: Custom storage path
Workflow Settings
- Model selection (via Amp SDK or OpenRouter)
- Node-specific configurations (prompts, commands, conditions, etc.)
Documentation Structure
Getting Started
User Guide
API Reference
Workflow Examples
Technical
Contributing
Resources
Quick Links
Getting Help
Documentation Issues
If you find issues in the documentation, please open an issue on GitHub.
Technical Support
For technical support and questions:
- Check the FAQ
- Review the Troubleshooting
- Open an issue on GitHub
Join our community for discussions, tips, and best practices.
Contributing to Documentation
We welcome contributions to the documentation! See Contributing Guidelines for details.
Documentation Style Guide
- Use clear, concise language
- Include code examples where appropriate
- Link to related topics
- Keep documentation up to date with code changes
Adding New Documentation
- Create a new markdown file in the appropriate directory
- Update the navigation in
mkdocs.yml
- Update the Table of Contents
- Submit a pull request
Building Documentation Locally
Prerequisites
Installation
# Install MkDocs and plugins
pip install mkdocs mkdocs-material mkdocs-video pymdown-extensions
# Clone the repository
git clone https://github.com/PriNova/nebulaflow.git
cd nebulaflow
# Build the documentation
mkdocs build
# Serve locally
mkdocs serve
The documentation will be available at http://127.0.0.1:8000.
Using GitHub Actions
The documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch. See .github/workflows/deploy-docs.yml for the deployment workflow.
Versioning
Documentation is versioned alongside the code. See the Changelog for version history.
License
Documentation is licensed under the same license as the NebulaFlow project. See LICENSE for details.
Last Updated: 2026-01-21