privutil

PrivUtil

[!NOTE] This project was "developed" with Antigravity AI. I am the owner of the project and I am using it to help me with my development tasks and to learn more about AI development while vive coding. This project was started from scratch and it took the length of TROLL and TROLL2 movies to build.

PrivUtil is a privacy-first, offline-capable developer utility suite. Built with Go and React, it provides 65+ tools across 11 categories for data manipulation, formatting, conversion, generation, and more — all running locally with zero server tracking.

✨ Features

Data & Diff

Formatters & Converters

Generators

Encoding & Crypto

Developer Tools

Network Tools

Text & String

Math & Units

Date & Time

Web & DevOps

Media Tools

🚀 Quick Start

[!IMPORTANT] PrivUtil should NOT be installed via go install. This project uses an embedded web component that must be built separately. Standard go install fails to bundle these assets correctly, resulting in an incomplete application. Please use the pre-compiled binaries from the Releases page or build from source using the provided Makefile.

Docker

Check out the project packages here

docker pull ghcr.io/odinnordico/privutil:latest
docker run --rm -p 8090:8090 ghcr.io/odinnordico/privutil:latest

To keep the container running and auto-restart it if it ever exits, add a restart policy:

docker run -d --restart=unless-stopped -p 8090:8090 ghcr.io/odinnordico/privutil:latest

Running as a service (auto-restart)

To run PrivUtil under systemd with automatic restart on failure, use the provided unit at deploy/privutil.service:

sudo cp privutil /usr/local/bin/privutil
sudo cp deploy/privutil.service /etc/systemd/system/privutil.service
sudo systemctl daemon-reload
sudo systemctl enable --now privutil

The unit sets Restart=on-failure, so the process is relaunched within ~1s if it exits unexpectedly.

Download from Releases

Download the latest binary for your platform from the Releases page.

Linux / macOS

# Example for Linux AMD64
tar -xzf privutil-linux-amd64.tar.gz
./privutil

Windows

1. Right-click the .zip file and select Extract All...
2. Run privutil.exe

Build from Source

# Clone the repository
git clone https://github.com/odinnordico/privutil.git
cd privutil

# Build everything
make build

# Run
./privutil

Access at http://localhost:8090

CLI Options

./privutil --help

Options:
  -port string          Port to listen on (default "8090")
  -host string          Host to bind to (default "127.0.0.1"; use 0.0.0.0 for all interfaces)
  -allowed-hosts string Comma-separated extra Host header values to accept (for LAN/custom-domain access)
  -custom-dict string   Path to the spellchecker custom-dictionary file (default: <user-config-dir>/privutil/custom-dictionary.txt)
  -mcp                  Serve the in-process MCP endpoint at /mcp for local LLM agents (default true)
  -log-level string     Log level: debug or info (default "info")
  -version              Print version and exit

Environment variables: PORT, HOST, ALLOWED_HOSTS, CUSTOM_DICT, MCP, LOG_LEVEL

The server binds to loopback (127.0.0.1) by default and only accepts requests whose Host header is localhost/127.0.0.1/::1 (a DNS-rebinding defense). To expose it on a LAN, set -host 0.0.0.0 and add the reachable host name(s) to ALLOWED_HOSTS.

🤖 MCP Server (for AI agents)

PrivUtil exposes its tools to local LLM agents over the Model Context Protocol, served in-process by the same binary — no separate server or process is launched. It's a Streamable HTTP endpoint at /mcp, reachable at http://localhost:8090/mcp while PrivUtil is running.

Point your agent's CLI at that URL. For example, with Claude Code:

claude mcp add --transport http privutil http://localhost:8090/mcp

Or in a client config that takes MCP server definitions:

{
  "mcpServers": {
    "privutil": { "type": "http", "url": "http://localhost:8090/mcp" }
  }
}

• No login — access is gated by the same loopback bind + Host-header allowlist as the rest of the server; cross-origin browsers are refused (no CORS, Origin check), and the endpoint is body-size- and rate-limited. Every tool handler is panic-recovered.
• ~70 tools exposed (pure, offline, no side effects) spanning hashing/crypto, encoding, data & formats (JSON/YAML/XML/TOML/CSV, JSON→Go, SQL), text (diff, regex, case, tokens, spell-check, hidden chars), network (IP/subnet, URL, MIME, HTTP status), math/units/dates, generators (UUID/ULID/password/RSA/OTP), and dev utilities (cron, docker→compose, cert parse). Call tools/list for the full catalog.
• Disable it with -mcp=false / MCP=false.

🛠️ Development

Prerequisites

• Go 1.21+
• Node.js 18+
• Make

Makefile Commands

make build          # Build frontend + backend
make build-web      # Build React frontend only
make build-go       # Build Go binary only (requires web/dist to exist)
make run            # Build and run
make clean          # Clean build artifacts
make test           # Run all tests
make test-backend   # Go tests with coverage
make test-frontend  # Vitest tests
make test-coverage  # Generate HTML coverage reports
make lint           # Run all linters
make lint-backend   # go vet + go fmt
make lint-frontend  # ESLint
make proto          # Regenerate protobuf code

Project Structure

privutil/
├── cmd/privutil/       # Main application entry point
├── internal/
│   ├── api/            # gRPC service implementations (domain-grouped handlers)
│   └── server/         # HTTP/gRPC-Web server
├── proto/              # Protocol Buffer definitions and generated Go code
├── web/                # React frontend (Vite + Tailwind)
│   ├── src/components/ # UI tool components
│   ├── src/lib/        # Shared utilities and navigation
│   └── src/proto/      # Generated TypeScript proto bindings
└── Makefile

Request flow:

Browser (React + nice-grpc-web) → HTTP server (gRPC-Web wrapper) → gRPC handlers → Go business logic

🎨 Theme

PrivUtil features a Kawasaki Lime theme with dark/light mode toggle:

• Primary Accent: #76FF03 (Neon Green)
• Default Mode: Dark
• Toggle in the top-right header

🧪 Testing

Backend (Go)

• Coverage: 85%+ on core business logic
• 150+ tests covering all gRPC handler methods

go test -tags=manual -cover ./...

Frontend (React/Vitest)

• Dashboard, ThemeToggle, and component utilities coverage

cd web && npm test

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing
3. Make changes and add tests
4. Run linters: make lint
5. Run tests: make test
6. Commit using Conventional Commits: git commit -m "feat: Add amazing feature"
7. Push and open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

MIT License — See LICENSE for details.