Orchestrator VSCode Extension

Visual dashboard for the Orchestrator framework - manage PRDs, epics, tasks, agents, and commands directly in VSCode

Companion extension for the Orchestrator framework

Features

📋 PRD Management

View and manage Product Requirements Documents directly in your sidebar:

Status Indicators: Visual badges for backlog, active, and complete PRDs
One-Click Navigation: Jump directly to PRD files
Quick Actions: Parse PRD to Epic with a single click
Auto-Refresh: Updates automatically when PRD files change

🚀 Epic Tracking with Progress

Real-time progress tracking for all your epics:

Visual Progress Bars: See completion percentage at a glance
Hierarchical Tasks: Expandable tree showing all tasks and subtasks
Smart Calculation: Automatically calculates progress from markdown checkboxes
Task Navigation: Click any task to jump to its location in the epic file
Epic Actions: Start, sync, and close epics with context menu

💡 Ideas & Rules

Quick access to your project knowledge:

Ideas Backlog: Browse all captured ideas with metadata
Rules by Category: Organized development rules for easy reference
Framework Conventions: Quick access to Orchestrator best practices

🤖 Commands & Agents Reference

Discover and use Orchestrator framework capabilities:

Categorized Commands: Browse all available slash commands
Copy to Clipboard: One-click copy for easy use in Claude Code
Agent Directory: View all available AI agents with descriptions
Command Descriptions: See usage and purpose for each command

⚡ Real-Time Updates

Stay synchronized with your project:

File Watching: Automatically detects changes in .claude/ directory
Smart Debouncing: Efficient 300ms debounced updates
Instant Refresh: Manual refresh with Ctrl+Shift+R / Cmd+Shift+R

📦 Archive Feature

Keep your workspace organized by archiving complete or rejected items:

Smart Archiving: Archive buttons appear on items with archivable status
View Archive: Browse archived items with quick pick interface
Easy Restore: Restore any archived item with one click
Preserved History: Archived items retain all metadata and can be fully restored

Archivable Statuses:

PRDs: complete, rejected, converted
Epics: complete, cancelled
Ideas: rejected, converted
Rules: deprecated, superseded

🛡️ Robust Error Handling

User-friendly error messages and logging:

Missing Directory Warnings: Helpful setup guidance when .claude/ not found
Malformed File Handling: Clear errors for invalid frontmatter with quick fixes
Output Channel Logging: Detailed logs available in "Orchestrator" output channel
Graceful Degradation: Extension continues working even with some invalid files

Installation

From VSCode Marketplace (Coming Soon)

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

From VSIX File

Download the latest .vsix file from the releases
Open VSCode
Go to Extensions view
Click the "..." menu → "Install from VSIX..."
Select the downloaded file

From Source

git clone https://github.com/Willbots/orchestrator-vscode.git
cd orchestrator-vscode
npm install
npm run compile
# Press F5 to run in Extension Development Host

Requirements

VSCode: Version 1.85.0 or higher
Node.js: Version 18.0.0 or higher (for development)
Orchestrator Project: Workspace must contain .claude/ directory structure

Usage

Getting Started

Open an Orchestrator Project: Open any workspace that has a .claude/ directory
Find the Orchestrator Icon: Look in the Activity Bar (sidebar) for the rocket 🚀 icon
Explore the Views: The extension provides six tree views:
- Epics: Track epic progress and navigate tasks
- PRDs: Manage Product Requirements Documents
- Ideas: Browse your ideas backlog
- Rules: Reference development rules
- Commands: Discover available commands
- Agents: Browse available AI agents

Working with PRDs

Click on any PRD in the tree to open it
Right-click (or click the arrow icon) to "Parse to Epic"
The extension will create an epic with tasks based on the PRD

Tracking Epic Progress

Navigate to the Epics view
See real-time progress bars for each epic
Expand an epic to view all tasks and subtasks
Click any task to navigate to its location in the file
Use context menu actions:
- Start Epic: Begin working on the epic
- Sync Progress: Update epic status
- Close Epic: Note epic as complete

Using Commands

Open the Commands view
Browse commands by category
Click the copy icon to copy command to clipboard
Paste in Claude Code chat to execute

Archiving Items

Note an item as complete or rejected (update its status in frontmatter)
The archive button (📦) will appear on the item in the tree view
Click the archive button to archive the item
Confirm the operation in the dialog

Viewing and Restoring Archive

Click the "View Archive" button (🕐) in any tree view title bar
Select an item from the quick pick list
Confirm the restore operation
The item will be moved back to the active directory

Keyboard Shortcuts

Ctrl+Shift+R / Cmd+Shift+R - Refresh all views

Project Structure

The extension expects this directory structure in your workspace:

your-project/
└── .claude/
    ├── prds/           # Product Requirements Documents
    ├── epics/          # Epic implementation plans
    ├── ideas/          # Idea backlog
    ├── rules/          # Development rules
    ├── commands/       # Slash commands
    └── agents/         # AI agent definitions

Troubleshooting

Extension Not Loading

Problem: Extension sidebar doesn't appear Solution: Ensure your workspace contains a .claude/ directory

Empty Views

Problem: Tree views show no items Solution:

Verify .claude/prds/, .claude/epics/, etc. directories exist
Check that markdown files have proper frontmatter (see below)
Check VSCode Output → Orchestrator for error messages

Progress Not Updating

Problem: Epic progress doesn't reflect changes Solution:

Ensure tasks use standard checkbox format: - [ ] or - [x]
Use lowercase x or uppercase X (both work)
Try manual refresh: Ctrl+Shift+R / Cmd+Shift+R

Malformed Frontmatter Errors

Problem: "Invalid frontmatter" error appears Solution:

Click "Open File" in the error message
Verify YAML frontmatter is between --- delimiters
Required fields: name, status, created
Check for YAML syntax errors (indentation, colons, etc.)

File Watching Not Working

Problem: Changes don't trigger automatic refresh Solution:

Network drives may not support file watching reliably
Use manual refresh as a workaround
Check file permissions on .claude/ directory

For more detailed troubleshooting, check the logs:

Open Output panel: View → Output
Select "Orchestrator" from dropdown
Review error messages and warnings

Development

Building from Source

# Install dependencies
npm install

# Compile TypeScript
npm run compile

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

# Build production bundle
npm run package-extension

Running Tests

# Run all tests
npm test

# Tests run in isolated VSCode instance
# 174+ tests covering all functionality

Structure

orchestrator-vscode/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── commands/                 # Command implementations
│   ├── providers/                # Tree view providers
│   ├── models/                   # Data models
│   ├── utils/                    # Utilities (parser, logger, etc.)
│   └── test/                     # Test suite
├── dist/                         # Compiled output
├── scripts/                      # Build and publish scripts
├── package.json                  # Extension manifest
└── esbuild.js                   # Build configuration

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Write tests for new functionality
Ensure all tests pass (npm test)
Submit a pull request

Technical Details

Language: TypeScript with strict mode
Bundler: ESBuild for fast builds
Testing: Mocha + Chai + Sinon
Test Coverage: >80%
Bundle Size: ~33KB
Dependencies: Minimal (only gray-matter for YAML parsing)
External APIs: None (100% local file operations)

Known Limitations

Extension only works in workspaces with .claude/ directory structure
Progress calculation assumes standard markdown checkbox format
File watching may not work reliably on network drives or NFS mounts
No Windows/Linux-specific testing yet (primarily tested on macOS)

Roadmap

[ ] Add screenshot capture and visual demos
[ ] Cross-platform testing (Windows, Linux)
[ ] Custom icons instead of built-in VSCode icons
[ ] Settings panel for configuration
[ ] Command palette integration
[ ] Epic template creation
[ ] Export/import functionality

License

MIT License - see LICENSE file for details

Acknowledgments

Testing infrastructure inspired by tunnelfy
Built for use with Claude Code
Companion to the Orchestrator framework

Support

Issues: GitHub Issues
Orchestrator Framework: Orchestrator Docs
Discussions: GitHub Discussions