MicroCodex puts a Codex-style agent in a sub-1MB binary

MicroCodex is a local coding agent written in C++23 that packages OpenAI/Codex-style workflows into a binary smaller than 1MB. It runs in a terminal and supports one-shot prompts, an interactive terminal UI, local coding tools, durable conversations, and automatic context compaction.

Installation and usage

On macOS or Linux, the project provides a one-line installer:

''sh curl -fsSL https://github.com/paoloanzn/microcodex/releases/latest/download/install.sh | sh ''

After installation, run microcodex login to authenticate, then start the agent with microcodex. Users can also download platform-specific archives from the latest GitHub Release. Available builds include Apple Silicon/arm64 and x86_64 binaries for macOS, plus x86_64 and arm64 binaries for Linux. Linux requires the libcurl and OpenSSL runtime libraries.

Recommended reading

This frog SVG benchmark tests AI literalness

The installer selects the native build automatically. To install a specific version, users can set MICROCODEX_RELEASE, such as v0.1.0:

''sh curl -fsSL https://github.com/paoloanzn/microcodex/releases/latest/download/install.sh | MICROCODEX_RELEASE=v0.1.0 sh ''

Authentication uses an existing ChatGPT plan. microcodex login opens a browser-based flow, while microcodex login --device-auth supports remote or headless machines through a one-time code. OAuth credentials are stored under $CODEX_HOME, or ~/.codex when that variable is unset.

The agent can run interactively or accept a one-shot task. The project documentation gives this example:

''sh microcodex microcodex “Find the failing test, fix it, and run the relevant test suite” ''

Skills, safety, and building

MicroCodex discovers Codex filesystem skills under $CODEX_HOME/skills, falling back to ~/.codex/skills. Each skill requires a SKILL.md file with YAML frontmatter containing a name and description. Metadata is loaded into the agent’s instructions at session startup; the full skill is read only when its name or description matches the task.

The project is not a sandbox. Before launching the user’s shell, it applies a lexical denylist covering commands such as rm -f, rm -rf, git reset --hard, forced git clean, git checkout --, disk-formatting tools, and shutdown commands. The denylist is not a shell parser or complete security boundary: unrecognized or indirect destructive commands may pass through, and file operations run with the same permissions as the MicroCodex process.

Building from source requires a C++23 compiler, make, and—on Linux—libcurl and OpenSSL development files:

''sh git clone --recurse-submodules https://github.com/paoloanzn/microcodex.git cd microcodex make ''

The resulting executable is written to build/microcodex; make test runs the test suite. The repository is licensed under Apache-2.0. The project currently lacks MCP support, and text cannot be copied from the terminal during a MicroCodex session.