A Go-native, single-binary POSIX with 96.6% BusyBox test compatibility (591/612).

Why?

Well, I wanted to do an experiment on Harsness Engineering, and improve my "agentic development" skills, prompts, instructions and all that. I did LFS in my early 20's and I had this weird itch of "do your own thing" but left it alone for my own sanity. Still the POSIX concepts remained in the back of my head. Last year (2025) I started to learn Go-lang, and then LLMs got really good in December 2025. Good enough that I've been using it at work non stop since then.

During that time I got this notion that AI waste time formating output, so I started doing --json output in a lot of my work scripts and tools (to save some time for my robot friends). Eventually all of these random ideas boiled to the conclusion that I should make a complete implementation of POSIX utilities in Go, with a JSON output and a Go SDK, and then benchmark it against BusyBox. It's the "natural conclusion" ... right?

Also deepseek-v4-pro had an very agressive 75% discount until 2026/05/31 15:59 UTC, and I wanted to try pi.dev instead of Antigravity/ClaudeCode.

All things kind of aligned in the last month so here we are now.

I'm not the first to start something like this, there is cugo and go-posix, but sadly they seem to be abandoned, and no wonder! A project like this is a huge undertaking, its probably a year of solid work for 1 human, that being said, took about 3 weeks to do with AI, with the proper "harness" and "agentic development" approach, that's really something.

Anyway the project got into a point that I'm happy with the results, that's enough for me ☑️.

Honest and Obvious Recognitions

I want to be very clear about this:

The only reason this works is that there's a brutally thorough, existing corpus of tests to validate against. The AI iterated until it passed. Without BusyBox's tests, this project is just random hallucinated code. The test suite is the real hero.

• So check and support BusyBox project and take a look at its amazing test suite, it's a masterpiece of thoroughness and coverage, and it made this project possible.
• Also Mvdan Shell, it really saved my butt. Absolutely brilliant.
• And goawk, which I used for the awk implementation, another big save!

Finally: let's not kid ourselves, this project is 90% wiring the AI to do the heavy lifting, 10% is steering it in the right direction, the fact that I was able to "solo dev" this with an LLM, reproducing close to 99% of BusyBox's behavior in a completely different language shows that POSIX utilities are, at their core, text transformers with very well-defined contracts (do one thing and do it well).

Quickstart!

See wiki/sdk.md for the full Go SDK guide and wiki/usage.md for CLI usage and Docker recipes.

CLI (secondary)

# One-shot CLI invocation.
docker pull ghcr.io/ramayac/goposix:cli
docker run --rm ghcr.io/ramayac/goposix:cli ls --json /

Build & Test

make all          # vet + test + build
make test         # unit tests
make testsuite    # BusyBox integration tests (gates every commit)
make ci           # full pipeline (test + testsuite + coverage + docker)

Environment Variables

I think there should be more... right?

Performance Highlights

See Performance Quick Reference and Benchmarking Plan for full details.

Documentation (yes, we have docs and it's decent!)

• Go SDK Guide — typed client for all 78 utilities
• RPC API Reference
• JSON-RPC Protocol — raw socket protocol for non-Go clients
• Architecture
• Security Model
• JSON Schema
• Test Coverage & Compliance Matrix
• POSIX FAQ

Quick Project Principles

• Multicall Binary: Single binary dispatched via symlink or subcommand (goposix ls).
• Daemon-First: The default image starts the persistent JSON-RPC daemon. Use the Go SDK for programmatic access (60µs/call). CLI is available as a secondary interface (goposix:cli).
• No CGO: Static compilation for FROM scratch containers (CGO_ENABLED=0).
• Little Dependencies: Only 3 external Go modules: mvdan.cc/sh/v3 (shell interpreter), golang.org/x/sys (cross-platform syscalls), golang.org/x/term (terminal detection). No external libraries for flag parsing, output, or utility logic.
• --json Only: Structured output via --json long flag only — no short-form (-j) collision with POSIX flags (ouch!)
• POSIX Flag Parsing: Custom parser in pkg/common/flags.go with escape hatches for free-form utilities.

Does it work? damn right it does: KoreGoOS.