FluxLoop VSCode Extension

Visual Studio Code extension for managing FluxLoop AI agent simulation projects.

Features

🎯 Project-Centric Workflow

Create and manage multiple FluxLoop projects from the Activity Bar
Switch between projects with a single click
Automatic project discovery and configuration validation

📝 Input Management

View and edit base inputs from configs/input.yaml
Generate input variations using LLM or deterministic strategies
Browse generated inputs and recordings in dedicated views

🧪 Experiment Execution

Run experiments directly from VSCode
Monitor execution progress with real-time feedback
View runner configuration and iteration settings at a glance

📊 Results Exploration

Browse experiment outputs organized by run timestamp under an Experiments folder
Open traces, summaries, observations, and artifacts with one click
Parse results into human-readable Markdown timelines with Parse Results action
View parsed analysis outputs in the per_trace_analysis/ folder

🔴 Recording Mode (Advanced)

Toggle argument recording for complex function signatures
Enable/disable recording mode from Command Palette or Experiments view
Status panel shows current recording state and target file

ℹ️ System Status

Real-time CLI and SDK installation checks
Configuration validation for configs/ structure
Recording mode and environment status at a glance

Installation

Recommended: Install from Extension Marketplace

🎯 Cursor Users

Open Extensions sidebar (Cmd+Shift+X or click Extensions icon)
Search for "FluxLoop"
Click Install
Restart Cursor

Extension is automatically downloaded from Open VSX Registry

💻 VS Code Users

Open Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Search for "FluxLoop"
Click Install
Restart VS Code

Or install directly from VS Code Marketplace

Alternative: Manual Installation from VSIX

If you prefer manual installation:

Download the latest .vsix file from GitHub Releases
Open Command Palette (Cmd+Shift+P or Ctrl+Shift+P)
Type and select "Extensions: Install from VSIX..."
Select the downloaded .vsix file
Restart your editor

Required Dependencies

Install FluxLoop CLI and SDK:

pip install fluxloop-cli fluxloop

Quick Start

1. Create a Project

Open the FluxLoop Activity Bar and click "Create New Project…" or use Command Palette:

FluxLoop: Create FluxLoop Project

This will:

Prompt you to select a parent folder
Generate configs/ directory with project/input/simulation/evaluation configs
Create .env, examples/, inputs/, recordings/, experiments/ directories
Register the project and set it as active

2. Review Configuration

Navigate to the Inputs view to inspect base inputs from configs/input.yaml. Click any base input to open the config file directly.

Alternatively, go to Experiments → Current Experiment → Open configuration to review configs/simulation.yaml.

3. Generate Inputs

From the Inputs view, click "Generate New Inputs…" to launch the wizard:

Choose generation mode (Deterministic/LLM)
Select variation strategies (rephrase, verbose, error_prone, etc.)
Set limit and overwrite options
Enter LLM API key if needed (saved to VS Code secrets and .env)

Generated inputs will appear under Inputs → Generated Inputs.

4. Run Experiment

From the Experiments view:

Click Run Experiment (located next to Current Experiment)
Select execution environment (Local Python/Dev Container)
- Local Python: Runs with your current Python environment
- Dev Container: Runs inside an active Dev Container
- Docker: Coming soon
Optionally override iterations

Results will be saved to experiments/ and appear in the Results view.

5. View Results

The Results view lists recent experiment runs under an Experiments folder. Expand any run to see:

Parse Results – Generate human-readable Markdown timelines from traces
per_trace_analysis/ – Parsed analysis outputs (appears after parsing)
summary.json – aggregate statistics
traces.jsonl – detailed execution traces
observations.jsonl – observation stream
errors.json – error logs (if any)
logs.json – additional logs

Click Parse Results to convert experiment outputs into per-trace Markdown files. You can specify a custom output directory or use the default per_trace_analysis.

Recording Mode (Advanced)

For agents with complex call signatures (WebSocket handlers, callbacks, etc.), you can record actual arguments and replay them during experiments.

Enable Recording

Use Command Palette:

FluxLoop: Enable Recording Mode

Or run in terminal:

fluxloop record enable

This updates .env and configs/simulation.yaml to enable recording. The Status panel will show "Record Mode: Enabled".

Capture Arguments

Run your application normally. FluxLoop SDK will capture arguments to recordings/args_recording.jsonl.

Disable Recording

Use Command Palette:

FluxLoop: Disable Recording Mode

Or run:

fluxloop record disable

Configure Replay

Edit configs/simulation.yaml to use recorded arguments:

replay_args:
  enabled: true
  recording_file: "recordings/args_recording.jsonl"
  override_param_path: "data.content"

Now run experiments—FluxLoop will replay recorded arguments with generated input variations.

Configuration Files (v0.2.0)

FluxLoop projects use a multi-file configuration structure:

File	Purpose	Edited From
`configs/project.yaml`	Project metadata, collector settings	Projects view → Configure Project
`configs/input.yaml`	Personas, base inputs, LLM settings	Inputs view → Base Inputs (click to open)
`configs/simulation.yaml`	Runner, iterations, replay args	Experiments view → Open configuration
`configs/evaluation.yaml`	Evaluator definitions	(Future: Results view)

All configs are YAML files that can be edited directly. The extension watches for changes and automatically refreshes views.

Available Commands

Access via Command Palette (Cmd+Shift+P / Ctrl+Shift+P):

Project Management:

FluxLoop: Create FluxLoop Project
FluxLoop: Add Existing FluxLoop Project
FluxLoop: Switch FluxLoop Project
FluxLoop: Remove FluxLoop Project

Workflow:

FluxLoop: Generate Inputs
FluxLoop: Run Experiment
FluxLoop: Run Single Execution
FluxLoop: Show Status

Recording:

FluxLoop: Enable Recording Mode
FluxLoop: Disable Recording Mode
FluxLoop: Show Recording Status

Configuration:

FluxLoop: Open Configuration
FluxLoop: Select Execution Environment
FluxLoop: Configure Execution Wrapper

Results:

FluxLoop: Parse Experiment – Convert experiment traces to Markdown

Advanced Configuration

Execution Wrapper (uv, pipx, etc.)

If you use uv, pipx, or any other wrapper to run FluxLoop CLI, configure it via:

Command Palette:

FluxLoop: Configure Execution Wrapper

Enter the prefix (e.g., uv run) and the extension will automatically prepend it to all CLI commands.

Or manually in .vscode/settings.json:

{
  "fluxloop.executionWrapper": "uv run"
}

This setting is saved to your workspace and will be applied to all FluxLoop commands.

Virtual Environments

The extension creates terminals using your workspace's default shell. If you use a virtual environment (venv, conda, etc.), ensure it's activated in your terminal profile or use the executionWrapper setting to prefix commands appropriately.

Troubleshooting

CLI Not Found

Ensure FluxLoop CLI is installed:

pip install fluxloop-cli
# Or with uv:
uv pip install fluxloop-cli

Check the Status panel for installation status.

SDK Not Found

Install the FluxLoop SDK:

pip install fluxloop

The Status panel will verify SDK availability in your Python environment.

No Configuration Found

Make sure your project has a configs/ directory with required files:

project.yaml
input.yaml
simulation.yaml

Create a new project using FluxLoop: Create FluxLoop Project to scaffold this structure automatically.

Recording Not Working

Verify .env contains FLUXLOOP_RECORD_ARGS=true
Check configs/simulation.yaml → replay_args.enabled: true
Use FluxLoop: Show Recording Status to inspect current state

Development

Build Extension

cd packages/vscode
npm install
npm run compile

Package Extension

npm install -g vsce
vsce package

This produces a .vsix file that can be installed locally.

Contributing

See CONTRIBUTING.md for guidelines.

License

Apache License 2.0 - see LICENSE for details.