# LGH - LocalGitHub

**LGH (LocalGitHub)** is a lightweight local Git hosting service. It wraps `git http-backend` to provide GitHub-like HTTP access, running entirely on localhost - turning your local directory into a Git server. ## 🌐 Ecosystem LGH is the foundation of a local-first dev-toolchain for AI agents: - [ActionD](https://github.com/JoeGlenn1213/ActionD) — local CI/CD engine that listens to LGH git events and runs plugin jobs (MCP server with 22 tools, incl. the one-call `dev_cycle_run` commit→CI loop) - [actiond-web](https://github.com/JoeGlenn1213/actiond-web) — web console with live dashboard, SSE log streaming, and in-browser failure diagnosis - [homebrew-tap](https://github.com/JoeGlenn1213/homebrew-tap) — `brew install lgh` / `brew install actiond` ## ✨ Features - 🚀 **Lightweight** - Single binary, no external dependencies - 🔧 **Easy to Use** - Intuitive CLI commands, one-click repository setup - 🌐 **HTTP Access** - Standard Git HTTP protocol, compatible with all Git clients - 🔒 **Authentication** - Built-in Basic Auth with salted password hashing - 🛡️ **Read-Only Mode** - Optional read-only mode to protect repositories - 📡 **mDNS Discovery** - Automatic LAN discovery for team collaboration - 🌍 **Tunnel Support** - One-click expose to internet (ngrok, cloudflared) - ⚡ **Smart Archival (v1.2.0)** - `lgh up` / `lgh save` commands with auto .gitignore - 🤖 **MCP Server (v1.2.0)** - AI Agent integration (Cursor, Claude Desktop) ## 📦 Installation ### Option 1: Download Pre-built Binary (Recommended) Download the pre-built binary for your system — these links always point to the latest release: | OS | Architecture | Download | |------|------|------| | macOS | Apple Silicon (M1/M2/M3) | [lgh-darwin-arm64](https://github.com/JoeGlenn1213/lgh/releases/latest/download/lgh-darwin-arm64) | | macOS | Intel | [lgh-darwin-amd64](https://github.com/JoeGlenn1213/lgh/releases/latest/download/lgh-darwin-amd64) | | Linux | x86_64 | [lgh-linux-amd64](https://github.com/JoeGlenn1213/lgh/releases/latest/download/lgh-linux-amd64) | | Linux | ARM64 | [lgh-linux-arm64](https://github.com/JoeGlenn1213/lgh/releases/latest/download/lgh-linux-arm64) | | Windows | x86_64 | [lgh-windows-amd64.exe](https://github.com/JoeGlenn1213/lgh/releases/latest/download/lgh-windows-amd64.exe) | ```bash # Install after download (macOS ARM64 example) chmod +x lgh-darwin-arm64 sudo mv lgh-darwin-arm64 /usr/local/bin/lgh ``` #### Windows Installation 1. Download `lgh-windows-amd64.exe` 2. Rename to `lgh.exe` 3. Move to a folder in your `%PATH%` (e.g., `C:\Program Files\lgh\`) 4. Run in PowerShell or Command Prompt ### Option 2: Install Script ```bash # Install curl -sSL https://raw.githubusercontent.com/JoeGlenn1213/lgh/main/install.sh | bash # Uninstall curl -sSL https://raw.githubusercontent.com/JoeGlenn1213/lgh/main/uninstall.sh | bash ``` ### Option 3: Homebrew (macOS) ```bash # Add tap brew tap JoeGlenn1213/tap # Install brew install lgh # Uninstall brew uninstall lgh ``` ### Option 4: Build from Source ```bash git clone https://github.com/JoeGlenn1213/lgh.git cd lgh make build sudo make install # Or manually go build -o lgh ./cmd/lgh/ sudo mv lgh /usr/local/bin/ ``` ### Option 5: Go Install ```bash go install github.com/JoeGlenn1213/lgh/cmd/lgh@latest ``` ## 🚀 Quick Start ### 1. Initialize LGH Environment ```bash lgh init ``` This creates the necessary directories and config files in `~/.localgithub/`. ### 2. Start the Server ```bash # Start in foreground lgh serve # Start in background (daemon mode) lgh serve -d # Check server status lgh status # Stop the server lgh stop ``` Server listens on `http://127.0.0.1:9418` by default. ### 3. One-Step Add & Push (v1.0.9+) The fastest way to host a local project: ```bash cd your-project lgh add . --push ``` This single command will: 1. Initialize a Git repo (if not already one). 2. **Auto-Commit** all files (if the repo is empty). 3. Register it with LGH. 4. **Auto-Push** to the server immediately. ### 4. Add Without Pushing If you prefer manual control: ```bash lgh add . # Then push manually later git push -u lgh main ``` ### 5. Smart Archival (v1.2.0+) The fastest way to backup and sync your code: ```bash # One-click: auto .gitignore + add + commit + push lgh up "commit message" # Local save only (no push) lgh save "WIP: work in progress" ``` **Smart Ignore** automatically: - Detects project type (Python, Go, Node, Java, Rust, AI/ML) - Generates appropriate `.gitignore` file - Blocks large files (>50MB) and sensitive files (.env, *.key) - **(v1.2.3+)** When used via MCP, returns exact `triggered_job_ids: [...]` array, allowing AI to track pipeline status with zero blind spots ### 5. Push Code After adding, you can use standard Git commands: ```bash git push lgh main # or git push ``` ### 5. Clone from Elsewhere ```bash git clone http://127.0.0.1:9418/your-project.git ``` ## 📖 Command Reference | Command | Description | Example | |------|------|------| | `lgh init` | Initialize LGH environment | `lgh init` | | `lgh serve` | Start HTTP server | `lgh serve -d` | | `lgh stop` | Stop running server | `lgh stop` | | `lgh add` | Add repository to LGH | `lgh add . --name my-repo` | | `lgh list` | List all repositories (detailed) | `lgh list` | | `lgh status` | View server status and repo list | `lgh status` | | `lgh remove` | Remove repository (use status/list first) | `lgh remove my-repo` | | `lgh tunnel` | Expose to internet | `lgh tunnel --method ngrok` | | `lgh auth` | Manage authentication | `lgh auth setup` | | `lgh -v` | Show version | `lgh -v` | | `lgh doctor` | Check system health | `lgh doctor` | | `lgh repo status` | Check repo connection state | `lgh repo status` | | `lgh remote use` | Switch active remote | `lgh remote use lgh` | | `lgh clone` | Simple clone from LGH | `lgh clone repo-name` | | `lgh events` | View/watch system event logs | `lgh events -n 20 --watch` | | `lgh up` | One-click commit and push (MCP returns ActionD triggered_job_ids) | `lgh up "message"` | | `lgh save` | Local save (no push) | `lgh save "WIP"` | | `lgh log` | View server logs | `lgh log --level ERROR` | | `lgh mcp` | Start MCP server for AI | `lgh mcp` | ### Repository Management (v1.0.4+) LGH provides tools to manage your local repository state without complex git commands. #### Check Connection State See exactly which remote you are pushing to: ```bash lgh repo status ``` #### Switch Remote Easily switch between LGH and origin (e.g., GitHub): ```bash lgh remote use lgh # Switch upstream to LGH lgh remote use origin # Switch upstream to Origin ``` #### Other Tools ```bash # Clone easily (no full URL needed) lgh clone my-project # Inspect bare repo details (HEAD, branches) lgh repo inspect my-project # Set default branch for bare repo lgh repo set-default my-project main # Check system health lgh doctor ``` ### Monitoring & Logs (v1.0.5+) Track system activity and repository changes in real-time. ```bash # View recent events lgh events # Watch for new events (like 'tail -f') lgh events --watch ```bash # Filter by type lgh events --type git.push ``` ### Agent Integration (v1.1.0+) LGH is designed to be the "source of truth" for AI Agents. **1. Real-time Subscription (Socket)** Connect to the Unix Domain Socket at `~/.localgithub/lgh.sock` to receive a real-time stream of JSON events for every action (repo added, git push, etc.). * **Protocol**: Unix Socket, JSON Lines. * **Security**: Read-Only. Only the local user can connect. **2. Event Replay (Simulation)** Inject past events back into the system to test your Agents without performing real Git actions. ```bash # Replay last 10 events to all connected agents lgh events replay --last 10 # Replay specific event types lgh events replay --type git.push ``` *Note: Replayed events include `“_replayed”: true` in their payload.* ### Server Options ```bash # Daemon mode (background) lgh serve -d # Read-only mode (disable push) lgh serve --read-only # Custom port lgh serve --port 8080 # Enable mDNS for LAN discovery lgh serve --mdns # Bind to all interfaces (LAN access) lgh serve --bind 0.0.0.0 ``` ## 🤖 MCP Quick Setup Guide Want to connect LGH to Cursor or Claude Desktop? ### Scenario 1: You already have LGH installed Simply update your AI editor's config file (e.g., `~/.cursor/mcp.json`) with: ```json { "mcpServers": { "lgh": { "command": "lgh", "args": ["mcp"] } } } ``` ### Scenario 2: You don't have LGH yet (One-Click Install) Run this single command to install the latest binary: ```bash curl -sSL https://raw.githubusercontent.com/JoeGlenn1213/lgh/main/install.sh | bash ``` Once installed, follow the "Scenario 1" step. We designed LGH as a single binary, so you **don't** need a separate "MCP Plugin". The `lgh` binary IS the MCP server! ### Verify Setup Ask your AI Agent: > "Check LGH status" If it calls `lgh_status` and responds, you're all set! ### Add Repository Options ```bash # Custom name lgh add . --name custom-name # Don't auto-add remote lgh add . --no-remote ``` ## 🔐 Authentication Enable authentication when sharing repositories over the network: ### Setup Authentication ```bash # Interactive setup (hidden password input) lgh auth setup # View auth status lgh auth status # Generate password hash (for manual config) lgh auth hash # Disable auth lgh auth disable ``` ### Client Authentication ```bash # Method 1: URL embedded credentials git clone http://username:password@192.168.1.100:9418/repo.git # Method 2: Use Git credential helper git config credential.helper store git clone http://192.168.1.100:9418/repo.git # Enter username/password on first access ``` ### Security Best Practices | Scenario | Recommended Config | |------|----------| | Local development | Default config (127.0.0.1) | | LAN sharing | `--bind 0.0.0.0 --read-only` + `auth setup` | | Internet exposure | Reverse proxy (Caddy/Nginx) + TLS + Auth | > ⚠️ **Security Note**: Password must be at least 8 characters. Config file stores salted hash, not plaintext. See [docs/SECURITY.md](docs/SECURITY.md) for detailed security guidelines. ## 🏗️ Directory Structure ``` ~/.localgithub/ ├── config.yaml # Global config ├── mappings.yaml # Repository mappings ├── lgh.pid # Server PID file └── repos/ # Bare repository storage ├── MyApp.git/ └── ProjectB.git/ ``` ## ⚙️ Configuration `~/.localgithub/config.yaml`: ```yaml port: 9418 bind_address: "127.0.0.1" repos_dir: "/Users/you/.localgithub/repos" read_only: false mdns_enabled: false # Authentication (optional) auth_enabled: true auth_user: "git-user" auth_password_hash: "salt:hash..." ``` ## 🌐 Tunnel Feature LGH supports multiple ways to expose your local service to the internet: ```bash # Show all available tunnel methods lgh tunnel # Use ngrok lgh tunnel --method ngrok # Use Cloudflare Tunnel lgh tunnel --method cloudflared # SSH reverse proxy lgh tunnel --method ssh ``` > ⚠️ **Security Note**: Always enable authentication (`lgh auth setup`) or use a reverse proxy before exposing to the internet. ## 🔧 Advanced Usage ### LAN Sharing (with Auth) ```bash # 1. Setup auth lgh auth setup # 2. Bind to all interfaces with read-only mode lgh serve --bind 0.0.0.0 --read-only --mdns # 3. Access from other devices (requires auth) git clone http://username:password@your-hostname.local:9418/repo.git ``` ### Production Deployment (Recommended) ```bash # 1. LGH listens on localhost only lgh serve # 2. Use Caddy reverse proxy + auto HTTPS # Caddyfile: # git.example.com { # basicauth * { # user $2a$14$... # } # reverse_proxy localhost:9418 # } ``` ### CI/CD Integration ```bash # Temporarily expose for GitHub Actions lgh auth setup lgh tunnel --method ngrok & # Use ngrok URL + credentials ``` ## ⚖️ Comparison with Other Solutions | Feature | LGH | GitLab | Gitea | git daemon | File Sharing | |---------|-----|--------|-------|------------|--------------| | Setup Complexity | ⭐ Single binary | ❌ Needs database | ⚠️ Needs config | ⭐ Simple | ⭐ No install | | HTTP Protocol | ✅ | ✅ | ✅ | ❌ | ❌ | | Authentication | ✅ Optional | ✅ Required | ✅ Required | ❌ | ❌ | | Web UI | ❌ | ✅ | ✅ | ❌ | ❌ | | Resource Usage | ⭐ <10MB | ❌ >1GB | ⚠️ ~100MB | ⭐ <5MB | ⭐ None | | Startup Time | ⭐ <1s | ❌ >30s | ⚠️ ~10s | ⭐ <1s | ⭐ Instant | | LAN Discovery | ✅ mDNS | ❌ | ❌ | ❌ | ✅ | | Use Case | Local/Temp | Enterprise | Team | Simple share | File transfer | **LGH's Position**: Fills the gap between "simple file sharing" and "full Git platform". ## 🧪 Testing ```bash # Run all tests go test ./... -v # Run integration tests go test ./test/... -v # Skip long-running tests go test ./... -v -short ``` ## 📋 System Requirements - **Go 1.23+** (for building) - **Git** (runtime) - **macOS**, **Linux**, or **Windows** ## 🤝 Contributing Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details. 1. Fork the repository 2. Create feature branch (`git checkout -b feature/amazing-feature`) 3. Commit changes (`git commit -m 'Add amazing feature'`) 4. Push to branch (`git push origin feature/amazing-feature`) 5. Create Pull Request ## 📄 License This project is licensed under the MIT License - see [LICENSE](LICENSE) file. ## 🙏 Acknowledgments - [spf13/cobra](https://github.com/spf13/cobra) - CLI framework - [spf13/viper](https://github.com/spf13/viper) - Configuration management - [fatih/color](https://github.com/fatih/color) - Terminal coloring - [hashicorp/mdns](https://github.com/hashicorp/mdns) - mDNS support ---

Made with ❤️ by JoeGlenn1213