The All-in-One Workflow Manager for Go Monorepos
Stop fighting with Makefiles and scripts. Start building.
gox is a workflow operating tool designed specifically for Go projects. It doesn't replace the Go toolchain; it orchestrates it. Whether you are building a single microservice or managing a massive monorepo with dozens of apps and libraries, gox makes your development lifecycle clean, predictable, and incredibly fast.
GitHub: https://github.com/pomagrenate/gox
When a Go project grows beyond go run main.go, things get messy. You end up with complex go.work setups, chaotic Makefiles, and custom bash scripts to manage multiple processes.
gox solves this by providing:
- 📦 Instant Monorepo Setup: Scaffolds a scalable Go workspace architecture in seconds.
- ⚡ Multi-Process Dev Runner: Run your API, Worker, and CLI simultaneously with beautifully color-coded logs.
- 🏗️ Smart Scaffolding: Add new microservices or shared libraries automatically linked to your
go.work. - 🩺 Built-in Doctor: Automatically detects missing dependencies, broken module links, and port conflicts!
- 🚀 One-Click Release: Cross-compiles lean, production-ready binaries for Windows, Mac, and Linux with SHA-256 checksums out of the box.
# Install via go install (recommended)
go install github.com/pomagrenate/gox/cmd/gox@latest
# Verify installation
gox --versionNote: Make sure your GOPATH/bin or GOBIN directory is in your system PATH. By default, go install places binaries in ~/go/bin/ (Unix) or %USERPROFILE%\go\bin (Windows).
# Clone the repository
git clone https://github.com/pomagrenate/gox.git
# Build the tool
cd gox
go build -o gox ./cmd/gox
# Move it to your PATH (Linux/Mac)
sudo mv gox /usr/local/bin/
# On Windows, move gox.exe to a folder in your System PATHgo install github.com/pomagrenate/gox/cmd/gox@latestCreate a brand new system with a standardized, scalable architecture.
gox init my-system
cd my-systemThis creates the gox.yaml, initializes go mod, go work, and creates standard directories (apps/, libs/, docs/, deployments/).
Add a new backend API and a background worker:
gox app add api
gox app add workerAdd a shared library:
gox lib add databasegox will generate the boilerplate code, run go mod init, and automatically link them in go.work and gox.yaml.
Start all your services at once. No more opening 5 different terminal tabs!
gox dev(Enjoy the color-coded output, graceful shutdown, and unified logging)
| Command | Description |
|---|---|
gox init [name] |
Initialize a new gox workspace and project tree structure. |
gox app add <name> |
Generate a new application inside apps/ and link it. |
gox lib add <name> |
Generate a new library inside libs/ and link it. |
gox dev |
Start all applications defined in the tasks.dev block of gox.yaml. |
gox build [app] |
Compile all apps (or a specific app) and place binaries in bin/. |
gox test [module] |
Run go test ./... recursively across all workspace apps and libs. |
gox doctor |
Run diagnostics to find port conflicts, missing directories, and environment issues. |
gox release [version] |
Cross-compile optimized production binaries (Windows, Linux, macOS) to dist/ with checksums. |
Your entire ecosystem is orchestrated by a single gox.yaml file at the root of your project:
name: my-system
apps:
api:
path: apps/api
main: ./cmd/api
port: 8080
worker:
path: apps/worker
main: ./cmd/worker
libs:
database:
path: libs/database
tasks:
dev:
- run: api
- run: worker
release:
targets:
- windows/amd64
- linux/amd64
- darwin/arm64Tired of weird errors because someone forgot to add a folder or two apps are fighting for port 8080? Just ask the doctor:
$ gox doctor
--- Gox Doctor ---
✅ Go installed: go version go1.22.0
✅ App 'api' directory exists
❌ Port conflict: App 'worker' and 'api' both use port 8080
⚠️ Found 1 issue(s) that need your attention.gox is not a package manager or a Go replacement. The Go official toolchain is incredibly powerful. gox simply acts as the missing workflow operating layer.
go command = Engine
gox = Steering Wheel