VSCode Extension Manual

Complete guide to the FlowMason VSCode extension - visual pipeline editing, debugging, testing, and more.

The FlowMason VSCode extension (v0.9.5) provides a native IDE experience for building, debugging, and testing AI pipelines directly in Visual Studio Code.

Installation

From Marketplace

1. Open VSCode
2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
3. Search for “FlowMason”
4. Click Install

From VSIX File

code --install-extension flowmason-0.9.5.vsix

From Source

cd vscode-extension
npm install && npm run compile && npm run package
code --install-extension flowmason-0.9.5.vsix

Getting Started

1. Open a FlowMason Project

cd my-flowmason-project
code .

The extension activates automatically when it detects a flowmason.json file.

2. Start Studio

Use Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

• FlowMason: Start Studio - Start the backend server
• FlowMason: Stop Studio - Stop the server
• FlowMason: Restart Studio - Restart the server

Or click the Studio button in the status bar.

3. Create a Pipeline

1. Right-click in Explorer > “New FlowMason Pipeline”
2. Enter pipeline name
3. Opens in DAG Canvas editor

Or create manually:

// pipelines/my-pipeline.pipeline.json
{
  "name": "my-pipeline",
  "version": "1.0.0",
  "stages": []
}

4. Add Stages

In the DAG Canvas:

1. Click “Add Stage” or use Cmd+Shift+A
2. Select component from QuickPick
3. Configure in the sidebar panel

5. Run Pipeline

• Press F5 to run with debugging
• Press Ctrl+F5 to run without debugging
• Click the “Run” CodeLens above the pipeline

Language Features

IntelliSense

Get autocomplete suggestions for:

• Component names in pipeline JSON
• Configuration properties
• Template expressions ({{input.fieldName}})
• Decorator parameters in Python

Hover Documentation

Hover over any component to see:

• Description
• Input/output schemas
• Configuration options
• Usage examples

Diagnostics

Real-time validation catches errors:

• Invalid component references
• Missing required configuration
• Type mismatches
• Circular dependencies

Go to Definition

Press F12 or Cmd+Click on a component name to jump to its definition.

Find References

Find all usages of a component across your project.

Document Symbols

See pipeline structure in the Outline view (Cmd+Shift+O).

CodeLens

Inline actions appear above stages:

• Run Stage - Execute just this stage
• Debug Stage - Start debugging at this stage
• View Output - See the stage’s last output
• Preview - Preview component output

Visual DAG Editor

Open any .pipeline.json file and click the DAG icon in the toolbar to see your pipeline as a visual graph.

Features

• Drag to rearrange stages
• Click to select and configure
• Right-click for context menu
• Auto-layout options
• Zoom and pan controls
• Connection handles for dependencies

Adding Stages

1. Click “Add Stage” button or press Cmd+Shift+A
2. Select a component from the QuickPick
3. Configure in the sidebar panel
4. Drag to position

Stage Configuration Panel

When a stage is selected, the sidebar shows:

• Stage ID and component type
• Input configuration fields (auto-generated from schema)
• Dependencies selector
• Apply/Reset buttons

Activity Bar Views

Click the FlowMason icon in the Activity Bar to see:

FLOWMASON
├── Components
│   ├── Nodes
│   │   ├── generator
│   │   ├── critic
│   │   └── improver
│   ├── Operators
│   │   ├── http-request
│   │   ├── json-transform
│   │   └── filter
│   └── Control Flow
│       ├── conditional
│       ├── foreach
│       └── trycatch
├── Pipelines
│   ├── main.pipeline.json
│   └── etl.pipeline.json
├── Runs
│   ├── run-abc123 (completed)
│   └── run-def456 (running)
├── Tests
│   └── main.test.json
├── Marketplace
│   ├── Featured
│   ├── Trending
│   ├── New
│   └── Categories
└── Time Travel
    └── (During debug session)

Components Panel

Browse all available components:

• Click to preview component details
• Double-click to insert into pipeline
• Drag-and-drop to DAG canvas

Pipelines Panel

View all pipelines in your project:

• Run status indicators (ready/running/completed/failed)
• Quick run buttons
• Recent execution history

Runs Panel

Monitor pipeline executions:

• Real-time status updates
• Click to view execution details
• Access logs and outputs

Debugging

The extension provides full Debug Adapter Protocol (DAP) support.

Breakpoints

Debug Session

1. Set breakpoints (F9 on a stage)
2. Press F5 to start debugging
3. Use debug controls:
   • F5 - Continue
   • F10 - Step Over (next stage)
   • F11 - Step Into (sub-pipeline)
   • Shift+F5 - Stop

Debug Panel

While debugging, inspect:

• Variables: Current stage inputs/outputs
• Watch: Custom expressions
• Call Stack: Pipeline → stage hierarchy

Prompt Editor

During debugging, the Prompt Editor panel shows:

1. Current Prompt: System and user prompts being sent
2. Edit Mode: Modify prompts live
3. Re-run: Execute stage with modified prompt
4. Compare: Side-by-side output comparison
5. History: Previous prompt versions
6. Token Streaming: Watch tokens arrive in real-time

Workflow:

1. Set breakpoint on LLM stage
2. Start debugging (F5)
3. When paused, open Prompt Editor
4. Edit the prompt
5. Click “Re-run Stage”
6. Compare outputs
7. Save successful prompt as new version

Time Travel Debugging

Step backwards through execution history to find bugs.

Commands

• FlowMason: Step Back - Go to previous snapshot
• FlowMason: Step Forward - Go to next snapshot
• FlowMason: View Snapshot - View snapshot details
• FlowMason: Compare Snapshots - Diff two snapshots
• FlowMason: Replay from Snapshot - Re-execute from snapshot
• FlowMason: What-If Analysis - Run with modified inputs

Test Explorer Integration

Tests appear in VSCode’s Test Explorer with full integration.

Test File Format

Create .test.json files:

{
  "name": "Pipeline Tests",
  "pipeline": "pipelines/main.pipeline.json",
  "tests": [
    {
      "name": "happy path",
      "input": { "url": "https://example.com" },
      "assertions": [
        { "path": "output.status", "equals": "success" }
      ]
    },
    {
      "name": "handles errors",
      "input": { "url": "invalid" },
      "assertions": [
        { "path": "error", "contains": "Invalid URL" }
      ]
    }
  ]
}

Running Tests

• Click play button in Test Explorer
• Use Cmd+; A to run all tests
• Use Cmd+; F to run tests in current file
• Right-click test > “Run Test”

Coverage

Coverage reports appear in:

• Test Explorer (per-file coverage percentage)
• Editor gutters (line-by-line coverage highlighting)
• Coverage panel (summary view)

Marketplace Integration

Browse and install pipeline templates from the community.

Features

• Browse: Featured, trending, and new pipelines
• Search: Search and filter by category
• Install: Install pipelines directly to workspace
• Publishers: View publisher profiles and their packages
• Favorites: Save favorite pipelines for later

Commands

• FlowMason: Search Marketplace - Search for pipelines
• FlowMason: Install from Marketplace - Install selected listing
• FlowMason: View Listing - View listing details
• FlowMason: View Publisher - View publisher profile
• FlowMason: Add to Favorites - Save to favorites

Commands Reference

Studio Management

Pipeline Editing

Execution & Debugging

Testing

Debug Configuration

Create .vscode/launch.json for custom debug configurations:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "flowmason",
      "request": "launch",
      "name": "Debug Pipeline",
      "pipeline": "${file}",
      "input": {
        "name": "test"
      },
      "stopOnEntry": false,
      "breakOnException": true
    },
    {
      "type": "flowmason",
      "request": "launch",
      "name": "Debug with Input File",
      "pipeline": "pipelines/main.pipeline.json",
      "inputFile": "test-inputs/sample.json",
      "stopOnEntry": true
    }
  ]
}

Settings

Configure the extension in VSCode settings (Cmd+,):

{
  "flowmason.studioHost": "localhost",
  "flowmason.studioPort": 8999,
  "flowmason.autoStartStudio": true,
  "flowmason.showCodeLens": true,
  "flowmason.diagnostics.enabled": true,
  "flowmason.debugger.showTokenStream": true,
  "flowmason.defaultProvider": "anthropic"
}

Status Bar

The status bar shows:

• Studio Status: Green dot (connected) or red dot (disconnected)
• Current Pipeline: Name of active pipeline
• Run Status: Ready / Running / Paused / Completed / Failed

Click the status bar item for quick actions.

Troubleshooting

Studio Won’t Start

# Check if port is in use
lsof -i :8999

# Kill existing process
kill -9 <PID>

# Start manually
fm studio start --port 8999

Extension Not Activating

1. Ensure flowmason.json exists in workspace root
2. Check Output panel > “FlowMason” for errors
3. Reload window (Cmd+Shift+P > “Reload Window”)

Debug Session Fails

1. Ensure Studio is running (check status bar)
2. Validate pipeline (fm validate pipeline.json)
3. Check API keys are configured in secrets
4. Check Output panel for error details

IntelliSense Not Working

1. Ensure file is saved with .pipeline.json extension
2. Wait for extension to fully activate
3. Check that pipeline JSON is valid
4. Reload window if needed

Tips & Best Practices

1. Use the DAG editor for visual pipeline design - it’s faster than editing JSON
2. Enable auto-start Studio to have the backend ready when you open a project
3. Use CodeLens to quickly test individual stages
4. Set breakpoints on LLM stages to iterate on prompts
5. Use Time Travel to debug issues by stepping backwards
6. Check diagnostics before running pipelines to catch errors early
7. Explore Marketplace to discover reusable pipeline templates
8. Use keyboard shortcuts for faster workflow (F5, F9, F10)