BranchPy
Log in

BranchPy Server

Version: 1.1.1
Last Updated: January 23, 2026
Status: Production

Overview

The BranchPy server is a unified daemon architecture combining WebSocket and HTTP transports for real-time updates and request/response APIs. It provides:

  • Auto-start on demand - Zero manual server management
  • Auto-recovery - Graceful handling of crashes and restarts
  • Multi-project support - Analyze multiple projects simultaneously
  • Dual transport - WebSocket (real-time) + HTTP (REST APIs)

Core Documentation

Document Purpose
README.md Overview and quick start (this document)
architecture.md System design, components, data flow
lifecycle.md Auto-start, auto-recovery, health checks
deployment.md Production deployment and configuration

Quick Start

Starting the Server

Automatic (recommended): The server starts automatically when you open a BranchPy feature in VS Code.

Manual:

# Start in daemon mode (background)
python -m branchpy server start

# Check status
python -m branchpy server status

# Stop server
python -m branchpy server stop

Accessing the Server

  • WebSocket: ws://127.0.0.1:8765/ws (real-time events)
  • HTTP: http://127.0.0.1:8766/ (REST API)
  • PILOT UI: http://127.0.0.1:8766/pilot/view?project=<path>

Key Features

✅ Fully Automated

  • Auto-start when needed
  • Auto-recovery from crashes
  • Auto-stop on VS Code exit
  • No manual intervention required

🔍 Health Monitoring

  • Status bar indicator in VS Code
  • Health check endpoints
  • Performance metrics
  • Structured logging

🌍 Multi-Project

  • Analyze multiple projects simultaneously
  • Per-project state isolation
  • Centralized project resolver
  • Concurrent operations

🔒 Robust

  • Port conflict resolution
  • Graceful error handling
  • Schema validation
  • Defensive programming

Architecture at a Glance

┌─────────────────────────────────────────────┐
│           VS Code Extension                  │
│  • Auto-start daemon                        │
│  • Health monitoring                        │
│  • Status bar UI                            │
└──────────────┬──────────────────────────────┘
               │
       ┌───────┴────────┐
       │                │
   WebSocket          HTTP
   Port 8765      Port 8766
       │                │
┌──────┴────────────────┴─────────────────────┐
│        BranchPy Unified Daemon               │
│  • Project state management                  │
│  • Watch subscriptions                       │
│  • Event broadcasting                        │
│  • PID tracking                              │
└──────────────────────────────────────────────┘
  • Technical/backend - Backend health and observability
  • Technical/api - API contracts and endpoints
  • Technical/events - Event bus and notification system
  • Technical/logging - Logging configuration
  • User-Guide/Settings - User-facing configuration

Source References

This document consolidates information from:

  • docs/v1.1.0/Server/README.md
  • docs/v1.1.0/Server/ARCHITECTURE.md
  • docs/v1.1.0/Server/LIFECYCLE.md