# Codex reimplemented in 8k lines of C++, <1MB binary

> Source: <https://github.com/paoloanzn/microcodex>
> Published: 2026-08-01 14:13:24+00:00

**MicroCodex** is an ultra-lightweight coding agent that runs locally in your terminal.

MicroCodex is written in C++23 and provides one-shot prompts, an interactive terminal UI, local coding tools, durable conversations, and automatic context compaction.

Run the following on Mac or Linux to install MicroCodex:

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

Then simply run `microcodex login`

to sign in, followed by `microcodex`

to get started.

## You can also go to the [latest GitHub Release](https://github.com/paoloanzn/microcodex/releases/latest) and download the appropriate binary for your platform.

Each GitHub Release contains these executables:

- macOS
- Apple Silicon/arm64:
`microcodex-aarch64-apple-darwin.tar.gz`

- x86_64:
`microcodex-x86_64-apple-darwin.tar.gz`

- Apple Silicon/arm64:
- Linux
- x86_64:
`microcodex-x86_64-unknown-linux-gnu.tar.gz`

- arm64:
`microcodex-aarch64-unknown-linux-gnu.tar.gz`

- x86_64:

Each archive contains a single entry with the platform baked into the name (for example, `microcodex-aarch64-apple-darwin`

), so you likely want to rename it to `microcodex`

after extracting it.

The installer selects the native build for the current architecture. Linux requires the libcurl and OpenSSL runtime libraries.

To install a specific release, set `MICROCODEX_RELEASE`

:

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

Run `microcodex login`

and open the displayed URL in your browser. MicroCodex stores the resulting OAuth credentials under `$CODEX_HOME`

, or `~/.codex`

when `CODEX_HOME`

is unset.

You can then start an interactive session or pass a one-shot prompt:

```
microcodex
microcodex "Find the failing test, fix it, and run the relevant test suite"
```

Warning

MicroCodex is not a sandbox. Model-requested commands and file operations run with the same permissions as the MicroCodex process.

MicroCodex discovers the same filesystem skills installed for Codex under
`$CODEX_HOME/skills`

, or `~/.codex/skills`

when `CODEX_HOME`

is unset. Each
skill must have a `SKILL.md`

with YAML frontmatter containing a `name`

and
`description`

. Skill metadata is added to the agent instructions at session
startup; the complete skill is read only when its name or description matches
the task.

Building requires a C++23 compiler, `make`

, libcurl development files, and OpenSSL development files on Linux.

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

The executable is written to `build/microcodex`

. Run the test suite with `make test`

.

- MCP support is not implemented yet.
- Text cannot currently be copied from the terminal while using MicroCodex.
- Dangerous shell commands are not yet gated by a safe-command policy.

This repository is licensed under the [Apache-2.0 License](/paoloanzn/microcodex/blob/main/LICENSE).