🚨 READ THIS ENTIRE FILE 🚨 CRITICAL: You MUST read this complete file from start to finish. Do not truncate or skip sections.
Essential reference for navigating the multi-terminal orchestrator codebase. Read this FIRST before implementing any feature.
IMPORTANT: Before creating pull requests, please update this document if you have added any new files or systems or made significant changes where the documentation is inaccurate.
ENTRY: server/index.js - Main server entry point
CORE: server/sessionManager.js - Terminal session management
SERVICES: server/statusDetector.js, gitHelper.js - Core services
FRONTEND: client/app.js, client/terminal.js - Web client
NATIVE: src-tauri/src/main.rs - Native desktop app
CONFIG: config.json, package.json - Configuration files
DIFF: diff-viewer/ - Advanced diff viewer component
PLANS: PLANS/ - Date-stamped planning + implementation notes
server/index.js - Express server with Socket.IO
├─ Manages: HTTP routes, WebSocket connections, service orchestration
├─ Key endpoints: /api/status, /api/sessions, /api/git
├─ Socket events: session-created, terminal-output, status-change
└─ Singleton services: SessionManager, StatusDetector, GitHelper
server/sessionManager.js - Terminal session lifecycle management
├─ Manages: PTY processes, session tracking, cleanup
├─ Key methods: createSession(), destroySession(), getActiveSessions()
├─ Cleanup hardening: closing sessions sends process-tree SIGTERM and a grace-timed SIGKILL fallback by PTY pid to reduce orphaned agent processes
├─ Stale-agent cleanup: when status detection sees an explicit shell/no-agent prompt, recovery `lastAgent` markers are cleared to keep sidebar status accurate (`no-agent` vs `busy/waiting`)
├─ Status model: periodic status re-evaluation prevents stale "busy" lights after output quiets down
└─ Uses: node-pty for terminal emulation
server/statusDetector.js - Claude Code session monitoring
├─ Detects: Claude sessions, branch changes, status updates
├─ Busy/idle heuristics: tool/typing signals are recency-gated to avoid stale "busy forever" states
├─ Events: session-detected, branch-changed, status-updated
└─ Polling: Configurable intervals for status checks
server/gitHelper.js - Git operations wrapper
├─ Operations: branch info, status, commit history, remote tracking
├─ Key methods: getCurrentBranch(), getStatus(), getBranchInfo()
└─ Error handling: Git command failures, repository state
server/notificationService.js - System notification manager
server/claudeVersionChecker.js - Claude Code version detection
server/tokenCounter.js - Token usage tracking (if applicable)
server/userSettingsService.js - User preferences and settings management
├─ Desktop onboarding state: persists Windows/Tauri dependency-onboarding completion in `global.ui.onboarding.desktopDependencySetup`
server/sessionRecoveryService.js - Session recovery state persistence (CWD, agents, conversations)
├─ Recovery filtering: stale/non-configured session entries are pruned when requested by workspace-scoped APIs
├─ Agent clearing: `clearAgent()` resets stale `lastAgent` markers when a Claude/Codex terminal falls back to plain shell
└─ Recovery metadata: recovery payload includes configured terminal/worktree counts for UI context
server/threadService.js - Workspace/project thread persistence (`~/.orchestrator/threads.json`)
├─ Thread identity: active-thread de-dup scopes by workspace + worktree + repository context
├─ Project identity: `projectId` is repository-scoped (`repo-path:*` / `repo-name:*`) instead of workspace-scoped when repository context is available
├─ Repository normalization: thread/worktree creation normalizes `.../master` and `.../workN` paths to repository root
├─ New chat reuse: thread creation prefers an existing repo worktree without an active thread before allocating a new `workN`
├─ Project aggregation: `listProjects()` returns repository-level chat rollups across one/many workspaces
└─ Lifecycle: create/list/close/archive + session association updates
server/projectBoardService.js - Local projects kanban board persistence (`~/.orchestrator/project-board.json`) + APIs (`GET /api/projects/board`, `POST /api/projects/board/move`, `POST /api/projects/board/patch`)
server/discordIntegrationService.js - Discord queue orchestration bridge (Services workspace ensure/start, signed queue verification, invocation idempotency, JSONL audit log for processing dispatch/replay/fail paths)
server/intentHaikuService.js - Session intent summarizer for context-switch hints (optional Anthropic Haiku model, heuristic fallback)
server/threadWorktreeSelection.js - Repository/worktree normalization + reuse-first candidate selection for thread creation
server/policyService.js - Role/action policy checks (viewer/operator/admin) for sensitive APIs + command execution
server/policyBundleService.js - Policy template catalog + bundle export/import for team governance profiles
server/pluginLoaderService.js - Plugin manifest validation/compatibility, command registration safety, and client slot metadata
server/agentProviderService.js - Provider abstraction layer for Claude/Codex/future agents (sessions, resume plans, history search, transcript fetch)
server/workspaceServiceStackService.js - Workspace service-stack manifest normalization/validation (services, env, restart policy, healthchecks)
server/configPromoterService.js - Team/shared service-stack baseline promotion + attach/resolve with optional signature verification
server/encryptedStore.js - Reusable AES-256-GCM encrypted JSON store helper for shared config artifacts
server/serviceStackRuntimeService.js - Workspace service-stack runtime supervisor (start/stop/restart, desired state, auto-restart, health checks)
server/auditExportService.js - Redacted audit export across activity + scheduler logs (JSON/CSV)
server/networkSecurityPolicy.js - Bind-host/auth safety policy helpers (loopback defaults + LAN auth guardrails)
server/processTelemetryBenchmarkService.js - Release benchmark metrics (onboarding/runtime/review), snapshot comparisons, release-note markdown generation
server/projectTypeService.js - Project taxonomy loader/validator for category→framework→template metadata (`config/project-types.json`)
server/workspaceManager.js - Workspace lifecycle management
├─ Manages: Workspace creation, switching, mixed-repo support
├─ Features: Dynamic terminal creation, worktree integration
└─ Storage: JSON-based workspace persistence
server/workspaceSchemas.js - Workspace configuration validation
├─ Schemas: JSON schema definitions for workspace types
└─ Validation: Ensures workspace integrity and structure
server/workspaceTypes.js - Workspace type definitions
├─ Types: Single-repo, mixed-repo, custom configurations
└─ Templates: Default settings for different workspace types
server/worktreeHelper.js - Git worktree operations wrapper
├─ Operations: Create, delete, manage git worktrees
├─ Bootstrap helper: `createProjectWorktrees({ projectPath, count, baseBranch })` for initial `workN` creation
├─ Integration: Seamless workspace-worktree coordination
└─ Safety: Path validation and cleanup handling
server/workspaceManager.js - Config cascade implementation
├─ Hierarchy: Global → Category → Framework → Project → Worktree
├─ Methods: getCascadedConfig(), getCascadedConfigForWorktree(), mergeConfigs()
├─ Features: Deep merge, worktree-specific overrides, cache prevention
└─ API: /api/cascaded-config/:type?worktreePath=...
server/configDiscoveryService.js - Dynamic config discovery
├─ Discovers: Game/framework/category configs from file hierarchy
├─ Structure: ~/GitHub/games/hytopia/.orchestrator-config.json
└─ Auto-detection: Scans master/ subdirectory for worktree-based projects
Config File Hierarchy:
~/GitHub/.orchestrator-config.json (Global)
~/GitHub/games/.orchestrator-config.json (Category)
~/GitHub/games/hytopia/.orchestrator-config.json (Framework)
~/GitHub/games/hytopia/games/HyFire2/.orchestrator-config.json (Project)
~/GitHub/games/hytopia/games/HyFire2/work1/.orchestrator-config.json (Worktree)
Config Structure:
{
"buttons": {
"claude": { "review": {...}, "replay": {...} },
"server": { "play": {...}, "build": {...}, "kill": {...} }
},
"gameModes": {
"deathmatch": { "flag": "--mode=deathmatch", "label": "Deathmatch" }
},
"commonFlags": {
"unlockAll": { "flag": "--unlock-all", "label": "Unlock All" }
}
}
client/app.js - Config pre-fetching & caching
├─ Methods: prefetchWorktreeConfigs(), fetchCascadedConfig(), ensureProjectTypeTaxonomy()
├─ Cache: Map<sessionId, config> for worktree-specific configs
└─ Extract: extractRepositoryName() from workspace config
client/app.js - Main client application
├─ Manages: UI state, socket connections, terminal grid
├─ Features: 16-terminal layout, real-time updates, session switching
├─ Command Palette: header `⌘ Commands` button + `Ctrl/Cmd+K` searchable command launcher for command-catalog actions
├─ Intent hints: compact "intent haiku" strip above each agent terminal, refreshed from `POST /api/sessions/intent-haiku`
├─ Projects + Chats automation: `project-chats-new` Commander/voice action supports explicit workspace + repository targeting
├─ Projects + Chats list: repository-first aggregation (project-centric view) while preserving workspace context for mixed workspaces
├─ Projects + Chats data source: prefers server-aggregated repository projects from `GET /api/thread-projects` with client fallback aggregation
├─ Status UI: visual state mapping for `busy`, `waiting`, `ready-new`, and `no-agent`
└─ Dependencies: Socket.IO client, terminal emulation
client/terminal.js - Terminal component implementation
client/terminal-manager.js - Terminal lifecycle management
client/file-watcher-adapter.js - File watching integration
client/notifications.js - Browser notification handling
client/workspace-switcher.js - Workspace switching interface
├─ Features: Quick workspace switching, status display
└─ UI: Dropdown selector with workspace metadata
client/workspace-wizard.js - Workspace creation wizard
├─ Features: Step-by-step workspace setup, repo selection
├─ Types: Single-repo, mixed-repo, and custom configurations
└─ Integration: Worktree creation and template application
client/greenfield-wizard.js - New-project wizard (greenfield creation flow)
├─ Uses project taxonomy categories before rendering
├─ Calls `orchestrator.createProjectWorkspace(options)` to centralize socket + REST fallback (`POST /api/projects/create-workspace`)
├─ Category → framework → template drilldown based on taxonomy relationships
├─ GitHub controls: supports optional local-only creation (`createGithub=false`), explicit repo target (`owner/repo` or URL), and optional GitHub org/user prefix
├─ Workspace-context suggestion (repo type -> recommended template/framework defaults)
└─ Full-screen wizard UI for project scaffolding + workspace creation
client/projects-board.js - Projects kanban board modal (Archive/Maybe One Day/Backlog/Active/Ship Next/Done; drag/drop + re-order; collapsible columns; live tag; hide forks; persists via `/api/projects/board`)
client/workspace-tab-manager.js - Multi-workspace tab management (NEW)
├─ Features: Browser-like tabs for multiple workspaces
├─ Manages: Tab creation, switching, state preservation
├─ XTerm lifecycle: Proper hide/show with fit() handling
├─ Notifications: Badge counts for inactive tabs
└─ Keyboard shortcuts: Alt+←/→, Alt+W, Alt+N, Alt+Shift+N, Alt+1-9
client/styles/tabs.css - Tab bar styling
├─ Features: Tab UI, badges, animations
└─ Responsive: Mobile and desktop layouts
client/styles/projects-board.css - Projects Board modal styling
client/plugin-host.js - Client plugin runtime for UI slots/actions
├─ Loads: `/api/plugins/client-surface` slot actions with cache/refresh support
├─ Exposes: `window.orchestratorPluginHost`
└─ Supports actions: open_url, open_route, copy_text, commander_action
The orchestrator now supports having multiple workspaces open simultaneously in browser-like tabs:
Key Features:
- Open multiple workspaces without closing others
- Seamless tab switching with preserved terminal state
- XTerm instances remain alive when switching tabs
- Notification badges show activity in inactive tabs
- Keyboard shortcuts for power users
- No visual glitches or layout shifts on switch
Architecture:
WorkspaceTabManager
├─ Tab Registry: Map<tabId, TabState>
├─ Active Tab Tracking: Current visible workspace
├─ XTerm Lifecycle: Hide/show with proper fit() timing
└─ Event Routing: Notifications for inactive tabs
TabState Structure:
{
id: 'tab-uuid',
workspaceId: 'workspace-id',
workspace: {...},
isActive: boolean,
notifications: number,
sessions: Map<sessionId, sessionData>,
terminals: Map<sessionId, xtermInstance>,
containerElement: DOMElement,
resizeObserver: ResizeObserver
}
Critical Implementation Details:
- Double
requestAnimationFrame()before fitting terminals (prevents race conditions) - Resize observers disconnected when hiding tabs
- Scroll positions and cursor states preserved
- Terminal output continues in background tabs
- Tab-aware session management in app.js
Usage:
- Click "+" button to open new workspace
- Click tab to switch
- Click "×" to close tab (confirms if terminals active)
Ctrl/Cmd+Kopens the command palette for quick command execution- Alt+← / Alt+→ to cycle tabs (previous/next)
- Alt+1-9 to jump to specific tab
- Alt+N for new workspace
- Alt+Shift+N for full-screen New Project wizard
- Alt+W to close current tab
Dashboard notes:
- "Create Workspace" card remains for workspace-only setup
- "New Project" card opens the greenfield wizard directly
- Terminal headers include a
✨quick action to open the New Project wizard from any session - Recovery prompt explicitly separates "recoverable sessions" from total configured worktree/terminal counts
### Native Desktop App (Tauri)
src-tauri/src/main.rs - Tauri application entry point ├─ Features: Native performance, system integration, tray icon ├─ Commands: File operations, system notifications, window management └─ Frontend: Rust backend + web frontend hybrid
src-tauri/src/terminal.rs - Native terminal integration src-tauri/src/file_watcher.rs - Native file watching src-tauri/src/lib.rs - Tauri application library
### Configuration Files
src-tauri/tauri.conf.json - Tauri app configuration src-tauri/Cargo.toml - Rust dependencies config.json - Shared application configuration package.json - Node.js dependencies and scripts
user-settings.json - User preferences and workspace settings user-settings.default.json - Default user settings template
### Workspace Templates & Scripts
templates/launch-settings/ - Workspace configuration templates ├─ hytopia-game.json - Gaming project workspace template ├─ website.json - Web development workspace template └─ writing.json - Writing/documentation workspace template
scripts/migrate-to-workspaces.js - Migration script for legacy workspaces ├─ Converts: Old workspace format to new multi-workspace format └─ Safety: Backup and rollback capabilities
scripts/public-release-audit.js - Public-release safety audit automation
├─ Checks: tracked cache/DB artifacts, public-doc path hygiene, loopback/auth defaults
└─ Optional: full-history gitleaks scan (--history-secrets)
scripts/create-project.js - Taxonomy-driven project scaffold generator (template/project-kit source resolution, optional post-create hooks, git init, optional GitHub remote, worktree bootstrap via WorktreeHelper)
## Advanced Diff Viewer Component
### Diff Viewer Architecture
diff-viewer/ - Complete diff analysis tool ├─ client/ - React frontend │ ├─ src/components/ - UI components │ └─ src/hooks/ - React hooks ├─ server/ - Express backend │ ├─ api/ - REST API endpoints │ ├─ diff-engine/ - Analysis engines │ └─ cache/ - Caching system └─ examples/ - Test cases
### Diff Viewer Core Components
diff-viewer/server/index.js - Diff viewer backend diff-viewer/server/api/diff.js - Diff processing API diff-viewer/server/api/ai-summary.js - AI analysis integration diff-viewer/server/diff-engine/engine.js - Core diff engine
diff-viewer/client/src/App.jsx - Main React application diff-viewer/client/src/components/DiffViewer.jsx - Primary diff component diff-viewer/client/src/components/SmartDiffViewer.jsx - Advanced analysis view
## Socket.IO Event System
### Server → Client Events
session-created: {sessionId, type, config} - New terminal session terminal-output: {sessionId, data} - Terminal output data session-destroyed: {sessionId} - Session cleanup status-change: {type, data} - Claude status updates git-change: {branch, status, commits} - Git repository changes notification: {type, message, level} - System notifications workspace-changed: {workspaceId, sessions} - Workspace switch completed workspace-list: {workspaces} - Available workspaces update
### Client → Server Events
create-session: {type, config} - Request new session destroy-session: {sessionId} - Close session terminal-input: {sessionId, input} - Send input to terminal request-status: {} - Request status update git-command: {command, args} - Execute git command switch-workspace: {workspaceId} - Switch to different workspace create-workspace: {config} - Create new workspace get-workspaces: {} - Request workspace list create-new-project: {name, category, template, ...} - Create project scaffold + workspace in one socket action close-tab: {tabId} - Close workspace tab and cleanup sessions (NEW)
## Configuration System
### Main Configuration (config.json)
```json
{
"server": {
"port": 3001,
"cors": {
"origins": ["http://localhost:2080", "tauri://localhost"]
}
},
"sessions": {
"maxConcurrent": 16,
"timeout": 3600000,
"cleanupInterval": 60000
},
"monitoring": {
"statusInterval": 5000,
"gitInterval": 2000
},
"logging": {
"level": "info",
"maxFiles": 5,
"maxSize": "10m"
}
}
PORT=3001
LOG_LEVEL=info
NODE_ENV=development
ENABLE_FILE_WATCHING=true
npm run dev - Start development server
npm run dev:client - Start client dev server
npm run tauri:dev - Start native app development
npm run dev:all - Start all services concurrently
# Diff viewer specific
cd diff-viewer && npm start - Start diff viewer
./start-diff-viewer.sh - Convenience script
SessionManager.getInstance() - Get session manager singleton
StatusDetector.startMonitoring() - Begin status monitoring
GitHelper.getCurrentBranch() - Get current git branch
NotificationService.send() - Send system notification
- Startup: 200-500ms vs 2-5s (browser)
- Memory: 150-300MB vs 600MB+ (browser)
- Latency: 15-50ms vs 50-150ms (browser)
- Terminal output buffering for performance
- Session cleanup to prevent memory leaks
- Efficient git status polling
- Socket.IO event throttling for high-frequency updates
GET /api/status - Server and session status
GET /api/sessions - List active sessions
POST /api/sessions - Create new session
DELETE /api/sessions/:id - Destroy session
GET /api/git/status - Git repository status
GET /api/git/branches - Available branches
GET /api/workspaces - List all workspaces
POST /api/workspaces - Create new workspace
PUT /api/workspaces/:id - Update workspace configuration
DELETE /api/workspaces/:id - Delete workspace
POST /api/workspaces/:id/switch - Switch to workspace
POST /api/workspaces/remove-worktree - Remove worktree from workspace config (mixed terminal arrays and numeric `terminals.pairs` modes), close linked sessions, prune matching recovery orphans even when config entry is already missing, keep files on disk
GET /api/threads - List project/workspace chats (`workspaceId` required)
GET /api/thread-projects - List repository-level chat projects aggregated from threads (optionally `workspaceId` scoped)
POST /api/threads - Create thread + ensure mixed worktree/session context
POST /api/threads/create - Alias for thread creation API used by Projects + Chats shell (idempotent for existing worktrees/sessions)
POST /api/threads/:id/close - Mark thread closed and close linked sessions
POST /api/threads/:id/archive - Archive thread (hidden unless includeArchived=true)
GET /api/project-types - Full project taxonomy (categories/frameworks/templates + metadata)
GET /api/project-types/categories - Project categories with resolved base paths
GET /api/project-types/frameworks?categoryId=... - Framework catalog (optionally scoped by category)
GET /api/project-types/templates?frameworkId=...&categoryId=... - Template catalog (optionally scoped)
POST /api/projects/create-workspace - Create project scaffold + matching workspace in one request
GET /api/discord/status - Discord queue + services health/status (counts + signature status); endpoint can be gated by `DISCORD_API_TOKEN`
POST /api/discord/ensure-services - Ensure Services workspace/session bootstrap; accepts optional `dangerousModeOverride` (gated by `DISCORD_ALLOW_DANGEROUS_OVERRIDE`)
POST /api/discord/process-queue - Dispatch queue processing prompt with optional `Idempotency-Key`/`idempotencyKey`, queue signature verification, idempotent replay, audit logging, and per-endpoint rate limiting
POST /api/sessions/intent-haiku - Generate <=200 char intent summary for an active Claude/Codex session
GET /api/greenfield/categories - Greenfield category list (taxonomy-backed)
POST /api/greenfield/detect-category - Infer category from description (taxonomy keyword matching)
GET /api/user-settings - Get user preferences
PUT /api/user-settings - Update user preferences
GET /api/process/telemetry/benchmarks - Live + snapshot benchmark rows for onboarding/runtime/review comparisons
POST /api/process/telemetry/benchmarks/snapshots - Capture a named benchmark snapshot for release tracking
GET /api/process/telemetry/benchmarks/release-notes - Build markdown release notes comparing current vs baseline benchmark
GET /api/policy/templates - Built-in team governance policy templates
POST /api/policy/bundles/export - Export policy bundle (template/current/custom) for sharing
POST /api/policy/bundles/import - Apply policy bundle (replace/merge) into global settings
GET /api/audit/export?signed=1 - Signed audit export (HMAC-SHA256; requires signing enabled + secret)
GET /api/agent-providers - List registered agent providers and capabilities
GET /api/agent-providers/:providerId/sessions - List provider sessions from SessionManager
POST /api/agent-providers/:providerId/resume-plan - Build provider-specific resume command/config plan
GET /api/agent-providers/:providerId/history/search - Provider-scoped history search (conversation index source-aware)
GET /api/agent-providers/:providerId/history/:id - Provider-scoped transcript retrieval
See "Socket.IO Event System" section above for complete event reference.
- Session Creation Failures: PTY spawn errors, resource limits
- Git Operation Failures: Repository state, permissions, network
- Socket Disconnections: Client reconnection, session recovery
- File System Errors: Permissions, disk space, path issues
- Automatic session cleanup on client disconnect
- Git operation retry with exponential backoff
- Graceful degradation when services unavailable
- Client-side error boundaries for UI stability
- Terminal input sanitization
- Git command argument validation
- File path restriction to project directory
- Socket event payload validation
- CORS configuration for allowed origins
- Session ownership validation
- Rate limiting for API endpoints
- File system access restrictions
ARCHITECTURE: Service-oriented with Socket.IO communication
SESSIONS: PTY-based terminal sessions with cleanup
MONITORING: Polling-based status detection with events
FRONTEND: Real-time UI updates via WebSocket
NATIVE: Tauri hybrid app with Rust backend
CONFIG: JSON-based configuration with environment overrides
LOGGING: Winston-based structured logging with rotation
- PTY sessions need proper cleanup to prevent resource leaks
- Socket.IO CORS must include all client origins (web + Tauri)
- Git operations should always be async with proper error handling
- Terminal output can be high-frequency - use throttling
- Native app requires different event handling than web client
- File watching can be resource intensive - use efficient patterns
- Workspace switching: Ensure all sessions are properly cleaned up before switch
- Worktree creation: Validate paths and handle existing worktree conflicts
- Mixed-repo workspaces: Terminal naming must avoid conflicts between repos
- Template validation: Always validate workspace templates against schemas
server/setupActionService.js - Defines setup actions and launches PowerShell installers
server/index.js - Routes: GET /api/setup-actions, POST /api/setup-actions/run
client/app.js - Guided dependency onboarding steps + diagnostics integration
client/index.html - Dependency onboarding modal markup + launch button
client/styles.css - Dependency onboarding progress/step styling
🚨 END OF FILE - ENSURE YOU READ EVERYTHING ABOVE 🚨