Architecture
FreeChaOS is an AI agent operating system, and the layout follows the metaphor literally.
┌───────────────────────────────────────────────┐│ Kernel ││ LLM comms layer → OpenAI / Anthropic / local │├───────────────────────────────────────────────┤│ Modules ││ Voice · Sandbox · Halluacinate │├───────────────────────────────────────────────┤│ Drivers ││ File system · Telegram · Google Play · GitHub│└───────────────────────────────────────────────┘Kernel
Section titled “Kernel”The kernel talks to LLM providers - OpenAI, Anthropic, local models. It is the only part of the system that cares about wire protocols and API formats. Provider adapters and provider-facing protocol shims live with the kernel, not in drivers/.
Internally the kernel speaks the Chaos-ABI, a neutral interface. Adapters translate it to whatever wire format a given provider expects, so adding a provider means writing one adapter (or, for OpenAI-compatible APIs, just a config entry). See Providers.
Modules
Section titled “Modules”Modules extend what ChaOS can do. Want voice? Module. Want a custom tool for your workflow? Module. Everything is modular - ChaOS is not locked into being a coding agent.
Notable modules:
- Sandbox - OS-native process confinement (landlock/seccomp, capsicum, pledge/unveil, macOS sandbox profiles).
- Halluacinate - the Lua scripting engine for user-defined tools, hooks, and the statusline.
- Clamping - see below.
Drivers
Section titled “Drivers”Drivers are MCP servers that give ChaOS its tools and connect it to the outside world. File reading, shell access, Telegram, Google Play - if it speaks MCP, it’s a driver. Plug in, wire up, ship. See Drivers (MCP).
Hardware philosophy
Section titled “Hardware philosophy”FreeChaOS runs on hardware you assemble from Temu parts. If it can’t run on a Core 2 Duo with 1 GB of RAM, it’s out of tree. In practice: ~80 MB RAM in MCP mode, ~128 MB in TUI mode.
Old hardware does not mean old software. FreeChaOS expects bleeding-edge operating systems and abuses every security primitive they offer:
| OS | Primitives |
|---|---|
| Linux 6.10+ | landlock, seccomp |
| FreeBSD 15+ | capsicum |
| OpenBSD | pledge, unveil |
| macOS 15+ | sandbox profiles |
No shims. No compatibility layers. If the OS gives us something, we use it. Windows is not supported.
Clamping / Docking
Section titled “Clamping / Docking”Anthropic requires MAX subscribers to use the official Claude Code harness. The Clamping module works within these terms: it launches Claude Code with --bare, strips its built-in tools, and connects through MCP. FreeChaOS provides the tools. FreeChaOS hooks into the lifecycle. Claude Code becomes the transport.
API key users connect directly through the kernel - no clamping needed.
This architecture is correct usage of both providers’ terms of service.
Origin & naming
Section titled “Origin & naming”FreeChaOS was forked from OpenAI Codex CLI. The fork exists because upstream refused to fix bugs and called them features. The codebase has since diverged significantly - FreeChaOS is provider-agnostic, modular, and built for hardware most projects have forgotten.
The name is a contraction of Chat OS, with the capitalization of OS echoing the BSD family (FreeBSD, OpenBSD, NetBSD). The Free prefix is GNU-style free-as-in-freedom - not “open” in the OpenAI sense.
Not to be confused with ChaosBSD - that’s a FreeBSD driver-staging fork, an OS for humans. FreeChaOS is an OS for LLMs.