phoenix

🔥 Phoenix

Live hot-reload runtime for Go applications with zero-downtime restarts.

Phoenix brings hot-reload to Go. Save your code, and Phoenix automatically rebuilds and restarts your application—on Linux/macOS, it even transfers open TCP connections to the new process so clients never disconnect.

✨ Features

• 🔄 Instant Rebuilds — File watcher detects changes and triggers builds automatically
• 🔌 Connection Handoff — Open TCP connections transfer to new process (Linux/macOS)
• 💾 State Preservation — Serialize sessions, caches, and counters across reloads
• ⚡ Incremental Builds — Source hashing skips rebuilds when nothing changed
• 🎨 Beautiful Output — Powered by Aurora for stunning terminal UI
• 📦 SDK Integration — Drop-in library for full hot-reload support in your apps
• 🪟 Cross-Platform — Works on Windows, Linux, and macOS

🚀 Quick Start

Installation

go install github.com/Summaw/GoPhoenix/cmd/phoenix@latest

Usage

phoenix ./cmd/myapp

That's it. Phoenix watches your files, rebuilds on save, and restarts your app.

With the SDK (Full Hot-Reload)

For connection handoff and state preservation, integrate the SDK:

package main

import (
    "net/http"
    "github.com/Summaw/GoPhoenix/pkg/sdk"
)

func main() {
    app := sdk.New(sdk.WithAddress(":8080"))

    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello from Phoenix! 🔥"))
    })

    app.ListenAndServe(mux)
}

🎬 Demo

╭────────────────────────────────────────────────────────────╮
│   ██████╗ ██╗  ██╗ ██████╗ ███████╗███╗   ██╗██╗██╗  ██╗   │
│   ██╔══██╗██║  ██║██╔═══██╗██╔════╝████╗  ██║██║╚██╗██╔╝   │
│   ██████╔╝███████║██║   ██║█████╗  ██╔██╗ ██║██║ ╚███╔╝    │
│   ██╔═══╝ ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║██║ ██╔██╗    │
│   ██║     ██║  ██║╚██████╔╝███████╗██║ ╚████║██║██╔╝ ██╗   │
│   ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝╚═╝╚═╝  ╚═╝   │
│                 Hot Reload Runtime for Go                  │
╰────────────────────────────────────────────────────────────╯
  12:34:56.789  ● INFO   Starting Phoenix
                ├─ target: ./cmd/server
                ├─ watch: .
                └─ binary: ./bin/app.exe
  12:34:56.812  ✓ SUCCESS  Build successful
                ├─ binary: ./bin/app.exe
                └─ duration: 156ms
  12:34:56.834  ✓ SUCCESS  Application started
                └─ pid: 12345
  12:35:02.123  ● INFO   Change detected
                └─ file: ./handlers/api.go
  12:35:02.456  ✓ SUCCESS  Build complete
                └─ duration: 203ms
  12:35:02.478  ✓ SUCCESS  Application restarted
                └─ pid: 12346

🔧 How It Works

┌─────────────────────────────────────────────────────────────┐
│                      Phoenix Daemon                          │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   📁 Watch Files  →  🔨 Rebuild  →  🔄 Handoff              │
│                                                              │
│   ┌──────────┐      ┌──────────┐      ┌──────────┐         │
│   │  .go     │      │ go build │      │  New     │         │
│   │  files   │  ──▶ │          │  ──▶ │ Process  │         │
│   │  change  │      │          │      │          │         │
│   └──────────┘      └──────────┘      └──────────┘         │
│                                              │               │
│                           ┌──────────────────┘              │
│                           ▼                                  │
│                    ┌─────────────┐                          │
│                    │ Transfer:   │                          │
│                    │ • Listeners │                          │
│                    │ • State     │                          │
│                    │ • Sessions  │                          │
│                    └─────────────┘                          │
└─────────────────────────────────────────────────────────────┘

On Linux/macOS, Phoenix uses Unix socket file descriptor passing (SCM_RIGHTS) to transfer open TCP listeners between processes—clients stay connected through the reload.

📋 CLI Options

phoenix [options] <package>

Options:
  -watch     Paths to watch (comma-separated)     default: "."
  -ext       File extensions to watch             default: ".go"
  -exclude   Paths to exclude                     default: "vendor,node_modules,.git"
  -bin       Output binary path                   default: "./bin/app"
  -drain     Graceful shutdown timeout            default: 30s
  -debug     Enable debug logging                 default: false

Examples:
  phoenix ./cmd/server
  phoenix -watch=./cmd,./internal ./cmd/api
  phoenix -ext=.go,.html -debug .

💾 State Preservation

Keep data alive across reloads:

type MyCache struct {
    data map[string]string
    mu   sync.RWMutex
}

func (c *MyCache) Snapshot() ([]byte, error) {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return json.Marshal(c.data)
}

func (c *MyCache) Restore(data []byte) error {
    c.mu.Lock()
    defer c.mu.Unlock()
    return json.Unmarshal(data, &c.data)
}

app := sdk.New(
    sdk.WithStateProvider("cache", myCache),
)

🆚 Comparison

📁 Project Structure

phoenix/
├── cmd/phoenix/          # CLI daemon
├── pkg/sdk/              # Application SDK
├── internal/
│   ├── watcher/          # File system monitoring
│   ├── compiler/         # Build orchestration
│   ├── handoff/          # Connection & state transfer
│   ├── process/          # Process lifecycle
│   └── state/            # State serialization
└── examples/basic/       # Demo application

⚠️ Platform Notes

On Windows, Phoenix performs a fast restart instead of true zero-downtime handoff (Unix sockets required for FD passing).

📄 License

MIT License — see LICENSE for details.

🙏 Credits

• Terminal UI powered by Aurora
• Inspired by Erlang's hot code loading

Like Phoenix? Give it a ⭐ to support the project!