DGx VS Code Extension

Connect your VS Code to DecisionGraph and orchestrate work through Claude Code with automated status synchronization.

Features

• Authentication against DecisionGraph API
• Secure credential storage using VS Code SecretStorage
• Client selection for multi-client consultants
• Local API server for Claude Code integration
• Story status synchronization to DecisionGraph
• Plan View (hierarchical Initiative → Epic → Story tree)
• Story selection interface with visual indicators
• Bulk story selection and multi-select
• Session Dashboard with real-time monitoring
• Todo list generation for Claude Code
• Automated work orchestration
• Session management (start/stop)
• Session persistence across VS Code restarts (.sessions/ files)

Installation

Prerequisites

• VS Code 1.85.0 or higher
• Node.js 20.x or higher
• Access to DecisionGraph backend API

Setup

1. Clone this repository
2. Run npm install to install dependencies
3. Run npm run compile to build the extension
4. Press F5 in VS Code to launch the extension in debug mode

Configuration

Configure the extension in VS Code settings:

{
  "dgx.apiUrl": "https://decisiongraph.io",
  "dgx.localApiPort": 3847,
  "dgx.autoStartLocalApi": true,
  "dgx.defaultView": "plan"
}

Settings

• dgx.apiUrl: DecisionGraph API base URL (default: https://decisiongraph.io)
• dgx.localApiPort: Port for local API server (default: 3847)
• dgx.autoStartLocalApi: Auto-start local API server on activation (default: true)
• dgx.defaultView: Default view mode - "plan" or "status" (default: plan)

Usage

Complete Workflow

1. Login & Setup

1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
2. Type "DecisionGraph: Login"
3. Enter your DecisionGraph username and password
4. Select your client (if you have multiple)
5. Your credentials are securely stored

2. Browse & Select Stories

1. Open the DecisionGraph sidebar (click the DecisionGraph icon in the activity bar)
2. Expand Plan View to see your work items:
   • 📋 Initiatives
   • 📁 Epics
   • Stories
3. Click on stories to select them (✓ = selected)
4. Select as many stories as you want to work on

3. Start Work Session

1. Click the ▶ Play button in the Plan View toolbar
2. The extension will:
   • Generate a todo list markdown file
   • Open it in the editor
   • Start the session
   • Activate the Session Dashboard

4. Let Claude Code Work

1. Claude Code reads the todo list
2. For each story, it will:
   • Fetch full details from the local API
   • Update status to "In Progress"
   • Implement the story based on requirements
   • Mark as "Complete" or "Blocked"
3. Monitor progress in the Session Dashboard

5. Monitor Progress

Watch the Active Session panel to see:

• ⟳ Current story being worked on
• ✓ Completed stories
• ⚠ Blocked stories (with reasons)
• ○ Remaining stories in queue

6. Complete Session

1. When all stories are processed, you'll see a summary
2. Click ■ Stop button to end the session
3. Review the session summary document

Local API Server

The local API server starts automatically when the extension activates (if configured). This server runs on http://localhost:3847 and provides endpoints for Claude Code to:

• Fetch story details
• Update story status
• Get next story to work on
• Check session status

API Endpoints (Local Server)

For Claude Code Integration

GET /api/story/:storyId
POST /api/story/:storyId/status
GET /api/session/next
GET /api/session/status
GET /health

Development

Project Structure

pgx-vscode/
├── src/
│   ├── extension.ts          # Main entry point
│   ├── api/
│   │   ├── oosClient.ts      # DecisionGraph API client
│   │   ├── localApiServer.ts # Local HTTP server
│   │   └── types.ts          # API type definitions
│   ├── auth/
│   │   ├── authService.ts    # Authentication management
│   │   └── credentialStore.ts # Secure credential storage
│   ├── models/               # Data models
│   └── utils/                # Utilities
├── out/                      # Compiled JavaScript
└── resources/                # Icons and assets

Building

npm run compile       # Compile TypeScript
npm run watch         # Watch mode for development
npm run lint          # Run ESLint

Testing

Currently implementing Phase 1. Testing involves:

1. Login/logout flows
2. Client selection
3. Local API server endpoints
4. DecisionGraph API integration

Troubleshooting

Cannot connect to DecisionGraph server

• Verify DecisionGraph backend is running
• Check dgx.apiUrl setting matches your DecisionGraph server URL
• Ensure network connectivity

Port already in use

• Another application is using port 3847
• Change dgx.localApiPort to a different port in settings
• Restart VS Code

Authentication fails

• Verify your username and password
• Check DecisionGraph server logs for authentication errors
• Try logging out and logging in again

Architecture

Authentication Flow

1. User enters credentials
2. Extension calls DecisionGraph /api/extension/auth/login
3. Token is stored securely in VS Code SecretStorage
4. Token is automatically injected into all DecisionGraph API requests
5. Token is verified on extension activation

Local API Server

• Binds to localhost only (security)
• Provides REST endpoints for Claude Code
• Proxies requests to DecisionGraph backend
• Manages active session state

Status Synchronization

• Claude Code calls local API to update status
• Local API maps local status to DecisionGraph status based on client configuration
• Status update is synced to DecisionGraph in real-time
• Session tracking is updated

Contributing

This is an internal tool. For bugs or feature requests, contact the DecisionGraph team.