Flox VSCode Extension

Flox: Your dev environment, everywhere.

Flox is a virtual environment and package manager all in one. With Flox you create environments that layer and replace dependencies just where it matters, making them portable across the full software lifecycle.

flox-vscode is a VSCode extension that integrates Flox environments with Visual Studio Code, providing a seamless UI for managing packages, environment variables, and services.

Features

🌐 Remote Development - Works with Remote SSH, Dev Containers, and WSL 🤖 AI Integration - MCP server for GitHub Copilot and AI assistants ✨ Sidebar UI - Manage your Flox environment directly from VSCode's sidebar 📦 Package Management - Install, upgrade, and remove packages with one click 🔧 Environment Variables - View and manage environment variables 🚀 Services - Monitor and control background services 🔄 Auto-sync - Automatic refresh when manifest files change 💻 Integrated Terminal - Environment variables automatically applied to terminals 🔔 Auto-Activation - Prompts to activate environment with remember preference 📌 Pending Indicators - Visual markers for uncommitted manifest changes 🔄 Auto-Reactivate - Environment refreshes when manifest.toml changes 📋 Service Logs - View real-time logs for running services 🐛 Debug Output - Detailed logs in the Output panel for troubleshooting ✅ Update Checks - Notifies when newer Flox versions are available 🎨 Status Bar - Shows active environment with custom Flox icon 📝 TOML Support - Syntax highlighting and validation for manifest.toml

Installation

Prerequisites

Flox: Install from flox.dev/docs/install-flox
VSCode: Version 1.87.0 or higher

Note: If Flox is not installed, the extension will display a message with a link to the installation guide.

From VSCode Marketplace

Open VSCode
Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
Search for "Flox"
Click "Install"

From .vsix File

code --install-extension flox-vscode-*.vsix

Quick Start

Creating Your First Flox Environment

# Navigate to your project directory
cd my-project

# Initialize a new Flox environment
flox init

# Install some packages
flox install nodejs python3 git

# Activate in VSCode
# Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
# Run: "Flox: Activate"

Using the Extension

Activating an Environment:

Open a project with a Flox environment (.flox/ directory)
Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
Run Flox: Activate
Environment activates in background and terminals get environment variables

Installing Packages:

Open the Flox sidebar view
Click the "+" icon in the Packages section
Enter the package name (e.g., nodejs, python3)
Package will be installed and available immediately

Viewing Environment Variables:

Open the Flox sidebar
Expand the "Variables" section
All environment variables from your manifest are listed

Managing Services:

View service status in the "Services" section
Start/stop services with the play/stop buttons
Check service logs in the Output panel

Commands

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

Flox: Init - Create a new Flox environment in current workspace
Flox: Activate - Activate the Flox environment
Flox: Deactivate - Deactivate the current environment
Flox: Install - Install a package
Flox: Uninstall - Remove a package
Flox: Upgrade - Upgrade a package to latest version
Flox: Edit - Open manifest in editor
Flox: Search - Search for packages in Flox catalog
Flox: Show service logs - Open terminal with live service logs
Flox: Configure Flox MCP Server - Set up MCP for Copilot
Flox: Install Flox - Open installation page (shown when Flox not installed)
Flox: Upgrade Flox - Open upgrade instructions (shown when update available)

Settings

Configure the extension behavior via VSCode settings:

Setting	Default	Description
`flox.promptToActivate`	`true`	Show popup when Flox environment is detected
`flox.checkForUpdates`	`true`	Check for Flox CLI updates (once per 24 hours)

Per-Workspace Behavior:

After activation prompt, choose "Always Activate" or "Never Activate" to remember preference
Preference is stored per-workspace in VSCode's workspace state

AI Integration (MCP)

The extension integrates with GitHub Copilot via the Model Context Protocol (MCP) to provide AI-powered Flox tools.

Prerequisites

VSCode 1.102 or higher
GitHub Copilot extension installed
flox-mcp command available in PATH (from Flox Agentic)

Setup

Activate your Flox environment
If flox-mcp is detected, a notification will appear
Click "Configure MCP" to enable the integration
Or run Command Palette → "Flox: Configure Flox MCP Server"

What You Get

Flox-specific tools available in Copilot Chat agent mode
Context-aware package suggestions
Environment management through natural language

FAQ

How does environment activation work?

The extension uses a background process for activation (no VSCode restart required!). This enables:

Remote SSH - Works with remote servers
Dev Containers - Works inside containers
WSL - Works with Windows Subsystem for Linux

The extension:

Spawns a background flox activate process
Captures all environment variables via IPC
Applies them to VSCode's integrated terminal
Ensures tools like Node.js, Python, etc. are available to other extensions

How does the extension detect Flox environments?

The extension looks for a .flox/ directory in your workspace root. When detected:

Sidebar view becomes available
Commands are enabled
File watchers monitor manifest.toml and manifest.lock for changes

What happens to my system packages?

Flox environments are isolated - your system packages remain unchanged. When you activate a Flox environment:

Flox packages take precedence in $PATH
System packages are still accessible as fallback
Deactivating restores your original environment

Can I use multiple Flox environments?

Currently, the extension supports one environment per workspace. For multiple environments:

Use VSCode multi-root workspaces
Layer environments at runtime (see Flox layering docs)
Switch between projects with different environments

Flox environments are fully reproducible:

# Commit the Flox manifest
git add .flox/env/manifest.toml .flox/env/manifest.lock
git commit -m "Add Flox environment"
git push

# Team members can activate immediately
git clone <your-repo>
cd <your-repo>
flox activate

Where can I find available packages?

VSCode: Use Flox: Search command
CLI: flox search <package-name>
Web: Browse at flox.dev

Flox has millions of package versions from the Nix ecosystem!

How do I view debug logs?

Open the Output panel (View → Output)
Select "Flox" from the dropdown
Logs show command execution, file changes, and activation lifecycle

How do I disable the activation prompt?

Global: Set flox.promptToActivate to false in settings Per-Workspace: Click "Never Activate" when prompted - this workspace won't prompt again

How do I disable update checks?

Set flox.checkForUpdates to false in settings to skip periodic Flox version checks.

What does the asterisk (*) mean next to a package?

Items with * are "pending" - they exist in manifest.toml but haven't been committed to the lock file yet. Run flox activate to apply changes.

🔧 Development

Want to contribute or modify the extension? Here's how to get started!

Prerequisites

Flox: Install from flox.dev
VSCode: Version 1.87.0 or higher
Git: For cloning the repository

Setup Development Environment

# 1. Clone the repository
git clone https://github.com/flox/flox-vscode.git
cd flox-vscode

# 2. Activate the Flox development environment
# This provides Node.js, npm, TypeScript, and all build tools
flox activate

# 3. Install npm dependencies
npm install

# 4. Compile TypeScript
npm run compile

Development Workflow

# Start watch mode (auto-recompile on changes)
npm run watch

# In VSCode, press F5 to launch Extension Development Host
# Or use "Run > Start Debugging"

The Extension Development Host window opens with your development version loaded. Make changes to the code, and reload the window (Cmd+R / Ctrl+R) to see updates.

Running Tests

# Run all tests (lint + unit tests)
npm test

# Run only linting
npm run lint

# Run only unit tests
npm run test:unit

Project Structure

flox-vscode/
├── .flox/                    # Flox development environment
├── src/
│   ├── extension.ts          # Extension entry point
│   ├── env.ts                # Core Flox integration
│   ├── view.ts               # TreeView providers (sidebar UI)
│   ├── config.ts             # Type definitions
│   └── test/                 # Tests
├── scripts/
│   └── activate.sh           # Background activation script
├── package.json              # Extension manifest
└── tsconfig.json             # TypeScript config

Key Development Commands

# Compile TypeScript
npm run compile

# Watch mode (auto-compile)
npm run watch

# Clean build artifacts
npm run clean

# Run tests
npm test

# Package extension as .vsix
npm run package

# Install packaged extension
code --install-extension flox-vscode-*.vsix

Debugging

Open the project in VSCode
Activate Flox environment: flox activate
Press F5 to launch Extension Development Host
Set breakpoints in TypeScript source files
Use Debug Console to inspect variables
Check Output panel for extension logs

Making Changes

Adding a New Command:

Register in src/extension.ts: env.registerCommand('flox.myCommand', handler)
Implement handler in src/env.ts
Add to package.json under contributes.commands
Test in Extension Development Host

Modifying the Sidebar:

Edit view classes in src/view.ts
Update getChildren() for new items
Update getTreeItem() for rendering
Refresh with _onDidChangeTreeData.fire()

Understanding Flox Integration:

src/env.ts - All Flox CLI interactions
scripts/activate.sh - Background process that captures env vars
File watchers monitor manifest.toml and manifest.lock for changes
Environment variables applied to VSCode terminals via environmentVariableCollection

Testing Your Changes

# 1. Compile your changes
npm run compile

# 2. Run tests
npm test

# 3. Launch Extension Development Host (F5)
# 4. Test functionality manually

# 5. Package and test the .vsix
npm run package
code --install-extension flox-vscode-*.vsix

Troubleshooting Development

Extension won't load:

Check for TypeScript errors: npm run compile
Verify package.json syntax
Check Output panel for error messages

Changes not reflected:

Ensure watch mode is running: npm run watch
Reload Extension Development Host (Cmd+R / Ctrl+R)
Check TypeScript compiled successfully

Flox environment issues:

Verify activation: flox list should show packages
Check manifest: flox list -c
Reinstall dependencies: npm install

Using Flox for Development

Why Flox?

Reproducible development environment
Same Node.js and npm versions for all contributors
No conflicts with system packages
Cross-platform (macOS, Linux)

Modifying the Development Environment:

# Add a development tool
flox install <package>

# View installed packages
flox list

# Edit manifest
flox edit

Running Commands Without Activating:

# Useful for CI/CD
flox activate -- npm test
flox activate -- npm run compile

Documentation

CLAUDE.md - Comprehensive development guide for Claude Code users
Architecture - See CLAUDE.md for detailed architecture documentation
VSCode Extension API - https://code.visualstudio.com/api
Flox Docs - https://flox.dev/docs

⭐️ Contribute

We welcome contributions to this project! Here's how:

Fork the repository
Clone your fork: git clone https://github.com/your-username/flox-vscode.git
Create a branch: git checkout -b feature/my-feature
Activate Flox: flox activate
Make changes and test thoroughly
Run tests: npm test
Commit: git commit -m "feat: add feature"
Push: git push origin feature/my-feature
Open a Pull Request

Please read the Contributor guide for detailed guidelines.

Contribution Guidelines

Follow existing code style (TypeScript strict mode)
Add tests for new features
Update documentation (README, CLAUDE.md)
Ensure all tests pass: npm test
Keep PRs focused on a single feature/fix

📚 Resources

📖 Flox Documentation - Learn about Flox
🚀 Get Support - Join Slack community
💬 Discourse Forum - Ask questions
🐛 Report Issues - File bugs or feature requests
📘 VSCode Extension API - Extension development guide

🪪 License

The Flox VSCode Extension is licensed under the GPLv2. See LICENSE.

Flox

Flox

Flox VSCode Extension

Features

Installation

Prerequisites

From VSCode Marketplace

From .vsix File

Quick Start

Creating Your First Flox Environment

Using the Extension

Commands

Settings

AI Integration (MCP)

Prerequisites

Setup

What You Get

FAQ

How does environment activation work?

How does the extension detect Flox environments?

What happens to my system packages?

Can I use multiple Flox environments?

How do I share my environment with my team?

Where can I find available packages?

How do I view debug logs?

How do I disable the activation prompt?

How do I disable update checks?

What does the asterisk (*) mean next to a package?

🔧 Development

Prerequisites

Setup Development Environment

Development Workflow

Running Tests

Project Structure

Key Development Commands

Debugging

Making Changes

Testing Your Changes

Troubleshooting Development

Using Flox for Development

Documentation

⭐️ Contribute

Contribution Guidelines

📚 Resources

🪪 License