Skip to content

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 pi 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:

  1. VS Code Extension: Runs in VS Code, manages the webview interface and workflow execution
  2. Webview UI: React-based interface using React Flow for visual graph editing

The extension uses the pi 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 configured pi provider authentication)

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

  • Provider authentication: Configure the selected provider through pi /login, auth.json, or its environment variable.
  • OPENROUTER_API_KEY: Optional for pi OpenRouter provider integration

VS Code Settings

  • nebulaFlow.storageScope: Choose between user or workspace storage
  • nebulaFlow.globalStoragePath: Custom storage path

Workflow Settings

  • Model selection (via pi SDK or OpenRouter)
  • Node-specific configurations (prompts, commands, conditions, etc.)

Documentation Structure

Getting Started

User Guide

API Reference

Workflow Examples

Technical

Contributing

Resources

Getting Help

Documentation Issues

If you find issues in the documentation, please open an issue on GitHub.

Technical Support

For technical support and questions: 1. Check the FAQ 2. Review the Troubleshooting 3. Open an issue on GitHub

Community

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

  1. Create a new markdown file in the appropriate directory
  2. Update the navigation in mkdocs.yml
  3. Update the Table of Contents
  4. Submit a pull request

Building Documentation Locally

Prerequisites

  • Python 3.11+
  • pip
  • Git

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