Profound Coder for Visual Studio Code

Bring AI-generated code changes from your Profound Coder server directly into your local IDE.

Overview

Profound Coder is a VS Code extension that complements the Profound Coder web UI by bringing completed AI-generated code changes into your local workspace. While you create and manage tasks through the web interface, this extension lets you:

• Browse completed tasks with code changes
• Preview AI-generated diffs side-by-side
• Apply changes at two levels of granularity (specific variant or individual file)
• Work with multi-repository projects
• Manage uncommitted changes safely with automatic git stashing

Important: This extension displays completed tasks only. To create tasks, manage environments, and monitor running tasks, use the Profound Coder web UI.

Key Features

Task Review & Application

• Completed Tasks: View tasks that have finished successfully and produced code changes
• Multi-Variant Support: When multiple AI agents (Claude, Codex, Gemini) work on the same task, see all variants grouped together
• Two Levels of Granularity: Apply a specific AI variant or individual files
• Side-by-Side Diff Preview: Review changes before applying using VS Code's built-in diff editor
• Multi-Repository Support: Handle projects spanning multiple git repositories

Profile Management

• Visual Profile Manager: Easily manage server connections
• Multiple Authentication Methods: API key or username/password login
• Profile Switching: Quick switching between different Profound Coder servers or accounts

Smart Git Integration

• Automatic Stash Management: Safely stash uncommitted changes before applying patches
• User Choice: Choose to stash, discard, or view changes when workspace is dirty
• Clean Application: Apply git patches with automatic whitespace handling

Filtering & Organization

• Pinned Tasks: Filter to show only pinned tasks for focused workflow
• Admin View: Admins can toggle between viewing their own tasks or all users' tasks
• Variant Grouping: Tasks run with the same parameters but different AI agents are grouped together
• Real-Time Refresh: Manual refresh to fetch latest completed tasks

Installation

From Visual Studio Marketplace

Search for "Profound Coder" in the VS Code Extensions marketplace and click Install.

From VSIX File

1. Download the .vsix file from your administrator
2. In VS Code, go to Extensions view (Ctrl+Shift+X / Cmd+Shift+X)
3. Click the ... menu → Install from VSIX...
4. Select the downloaded file

Licensing

This VS Code extension is licensed under the MIT License. However, using the extension requires access to a Profound Coder server, which is licensed separately. Please contact Profound Logic Software for server licensing information.

Getting Started

Prerequisites

• Profound Coder Server: v0.4.0 or later running and accessible
• User Account: Valid credentials (username/password or API key)
• Web UI Access: For creating and managing tasks
• Git Repositories: Project repositories open in VS Code workspace

Initial Setup

1. Open Profile Manager

When you first open VS Code, click the Profound Coder icon in the Activity Bar (left sidebar), then click the server icon in the toolbar.

Alternatively, press Ctrl+Shift+P (Cmd+Shift+P on Mac) and run:

Profound Coder: Manage Server Profiles

2. Create Your First Profile

1. Click "Create New Profile"
2. Enter a profile name (e.g., "production" or "local")
3. Enter your server URL (e.g., http://localhost:3000)
4. Enter your username and password, or API key
5. Click "Login & Create Profile"

The extension will authenticate your profile.

3. Verify Connection

Once created, your profile should show as "Connected" with your username displayed. The status bar at the bottom will show: ✓ Profound Coder [profile-name]

Usage Guide

Viewing Tasks

1. Open the Profound Coder View: Click the Profound Coder icon in the Activity Bar
2. Browse Completed Tasks: The tree view shows:
   • Single Tasks: Tasks run with one AI agent
   • Task Groups: Tasks run with multiple AI agents (variants)
3. Task Information: Each task shows:
   • Task name/description
   • AI agent(s) used (Claude, Codex, Gemini)
   • Changed files with line counts
   • Hover for full details including instructions

Understanding Variants

When you submit a task to multiple AI agents simultaneously (via the web UI), they appear grouped:

📋 "Fix login bug"
  ├── 🤖 Claude
  │   ├── 📁 backend/
  │   │   └── auth.js (+15 -8)
  │   └── 📁 frontend/
  │       └── login.vue (+3 -2)
  ├── 🤖 Codex
  │   └── 📁 backend/
  │       └── auth.js (+12 -5)
  └── 🤖 Gemini
      └── 📁 backend/
          └── auth.js (+18 -10)

You can choose which variant to apply, or apply individual files from any variant.

Previewing Changes

1. Click the diff icon next to any file
2. Side-by-side diff opens automatically
3. Review changes in VS Code's diff editor

To compare different AI approaches, preview the same file under different variants and choose which you prefer

Applying Changes

Apply Specific Variant

• Click the ↓ (Apply) icon next to your preferred variant
• All changes from that variant are applied
• Affects all repositories if the task spans multiple repos

Apply Single File

• Click the ↓ (Apply) icon next to any individual file
• Only that one file change is applied
• Useful for cherry-picking changes from different variants

Handling Uncommitted Changes

When you apply changes to a repository with uncommitted work, you'll see a dialog:

Options:

• Stash & Continue: Saves your changes to git stash, applies patch, keeps stash for later restoration
• Discard & Continue: Discards your uncommitted changes permanently, then applies patch
• View Changes: Opens Source Control view to review your uncommitted changes
• Cancel: Aborts the apply operation

Recommended: Use "Stash & Continue" to safely preserve your work.

Filtering Tasks

Pinned Tasks Only:

• Click the 📌 (Pin) icon in the toolbar to show only tasks you've pinned in the web UI. This is useful for focusing on specific work items.
• Click the clear icon to remove the filter

Admin: All Users' Tasks (Admin only):

• Click the 👥 (Organization) icon in the toolbar to view tasks from all users on the server
• Click the 👤 (Person) icon to return to your own tasks

Opening Tasks in Web UI

• Click the external link icon next to a task or variant to open the task in your browser for full details
• For task groups, opens all variants in a comparison view

Managing Profiles

Switch Profiles:

1. Click the server icon in the toolbar
2. Select a different profile from the list
3. Tasks list refreshes with the new server's data

Edit Profile:

1. Open Profile Manager
2. Select profile → click "Edit"
3. Update server URL or re-authenticate

Delete Profile:

1. Open Profile Manager
2. Select profile → click "Delete"
3. Confirm deletion (API keys are removed from local storage)

Working with Multi-Repository Projects

Profound Coder tasks can modify multiple repositories simultaneously. The extension handles this seamlessly:

Setup

Ensure all repositories are open in your VS Code workspace:

// .code-workspace file
{
  "folders": [
    { "path": "../backend" },
    { "path": "../frontend" },
    { "path": "../shared" }
  ]
}

Repository Matching

The extension matches repositories using:

1. Workspace folder name matching the repository's local_path
2. Folder path matching the repository's local_path
3. Parent directory structure

Viewing Multi-Repo Changes

When a task affects multiple repositories, the tree shows:

📋 "Add authentication feature"
  └── 🤖 Claude
      ├── 📁 backend (3 files)
      │   ├── auth.js (+45 -0)
      │   ├── middleware.js (+23 -5)
      │   └── config.js (+8 -2)
      └── 📁 frontend (2 files)
          ├── Login.vue (+67 -0)
          └── store/auth.js (+34 -0)

Applying Multi-Repo Changes

• Apply Variant: Changes are applied to each repository independently
• Per-Repository Stashing: Each repository's uncommitted changes are handled independently
• Partial Success: If one repository fails, others may succeed (status shown in notification)

Troubleshooting

"Cannot find repository" Error:

• Ensure the repository is open in your workspace
• Check that the folder name matches what the server expects
• Verify the repository is a valid git repository

Configuration

Profiles are stored in ~/.coder/profiles/ and managed via the Profile Manager webview.

Requirements

Server

• Profound Coder Server: v0.4.0 or later
• Network Access: VS Code must be able to reach the server URL
• Authentication: Valid user account with API access

Local Environment

• Git: Git CLI installed and available in PATH
• Workspace: Git repositories open in VS Code workspace
• Permissions: Write access to repository directories

For Task Creation

• Web UI: Use the Profound Coder web interface to:
  • Create and submit tasks
  • Configure environments
  • Manage templates
  • Monitor running tasks
  • Pin tasks for the extension to find

Known Issues & Limitations

By Design

• No Task Creation: Tasks must be created via the web UI
• Completed Tasks Only: Running, failed, or pending tasks are not shown
• No Environment Management: Configure environments in the web UI
• No Template Management: Create and edit templates in the web UI
• No Task Deletion: Delete tasks via the web UI

Current Limitations

• No Real-Time Updates: Task list must be manually refreshed (click refresh button)
• No Undo: Once applied, changes can only be reverted using git commands
• Repository Matching: Workspace folder name must match repository's local_path from server
• Large Patches: Very large patches (>10MB) may cause performance issues

Workarounds

"Cannot find repository" Error:

• Ensure workspace folders match server repository names exactly
• Check that folders are valid git repositories
• Try adding the repository at a different path in the workspace

API Key Expired:

• Open Profile Manager
• Re-login with username/password to generate new API key
• Or manually update the API key in the profile

Stash Not Restored:

• Manually restore using: git stash pop
• View stash list: git stash list

Troubleshooting

Connection Issues

Status Bar Shows "Cannot connect":

1. Check server URL in profile manager
2. Verify server is running: curl http://your-server:3000/health
3. Check firewall/network settings
4. Try testing connection in profile manager

"Unauthorized" or "Invalid API Key":

1. Open Profile Manager
2. Re-login with username/password
3. Or verify your API key is still valid on the server

Application Issues

"Cannot find repository":

1. Verify repository is open in workspace
2. Check workspace folder name matches server's local_path
3. Ensure folder is a valid git repository: git status

Patch Apply Failed:

1. Check git status: git status
2. Resolve any existing merge conflicts
3. Try applying individual files instead of entire variant
4. Check that file paths match between server and local

Changes Not Showing:

1. Click the refresh button in the toolbar
2. Verify task is marked as "completed" in web UI
3. Check that task has code changes (not just logs)
4. Verify you're viewing the correct profile

Git Issues

Stash Problems:

• View stashes: git stash list
• Restore manually: git stash pop
• Clear stashes: git stash clear (⚠️ careful!)

Applied Changes Look Wrong:

1. Check current git diff: git diff
2. Revert if needed: git checkout -- .
3. Re-apply with different variant
4. Check for whitespace issues: git apply --ignore-whitespace

Support

For issues or questions, please contact Profound Logic Support.

• Website: https://www.profoundlogic.com

---

Enjoy using Profound Coder! 🚀