Latest release {{release}}

The coding agent that fits in 1 MB

microcodex is an ultra-lightweight coding agent for your terminal. A single native binary that peaks at 15–20 MB of memory, and signs in with the ChatGPT plan you already pay for.

$ curl -fsSL https://github.com/paoloanzn/microcodex/releases/latest/download/install.sh | sh
api — microcodex — 104×41
› add email and password validation to the signup handler (passwords need 12+
characters), add tests, and run them
• Called read({"path":"src/handlers/signup.cpp","offset":0,"limit":16384})
└ #include "handlers/signup.h"
#include "validation/rules.h"
… +44 lines (ctrl + t to view full output)
}
} // namespace api::handlers
• Edited src/handlers/signup.cpp (+5 -1)
41 const auto body = json::parse(request.body());
42 - return createUser(body);
42 + const auto email = body.string("email").value_or("");
43 + if (!validateEmail(email)) return badRequest("email is invalid");
44 + const auto password = body.string("password").value_or("");
45 + if (!validatePassword(password, 12)) return badRequest("password is too short");
46 + return createUser(body);
47 }
• Ran make test && git diff --stat
└ {"stdout":"ok 1 - signup rejects a malformed email\nok 2 - signup rejects a short password\nok 3 - s
ignup accepts a valid payload\n3 tests, 0 failures\n src/handlers/signup.cpp | 6 +++++-\n tests/sign
up_test.cpp | 31 +++++++++++++++++++++++++\n 2 files changed, 36 insertions(+), 1 deletion(-)\n","stde
rr":"","exit_code":0}
• Added email and password validation to handleSignup. Invalid requests now get a 400
with a message, and passwords must be at least 12 characters.
Three new cases in tests/signup_test.cpp cover the rules; make test passes.
•◦Working ({{elapsed}}s • esc / ctrl + c to interrupt)
› Ask MicroCodex to do anything
gpt-6-sol · esc / ctrl + c interrupt ctrl + q quit gpt-6-sol · enter send ctrl + j newline ctrl + r reset ctrl + d quit
Binary
≈1 MB
Peak RSS
15–20 MB
api — microcodex — 104×41
› add email and password validation to the signup handler (passwords need 12+
characters), add tests, and run them
• Called read({"path":"src/handlers/signup.cpp","offset":0,"limit":16384})
└ #include "handlers/signup.h"
#include "validation/rules.h"
… +44 lines (ctrl + t to view full output)
}
} // namespace api::handlers
• Edited src/handlers/signup.cpp (+5 -1)
41 const auto body = json::parse(request.body());
42 - return createUser(body);
42 + const auto email = body.string("email").value_or("");
43 + if (!validateEmail(email)) return badRequest("email is invalid");
44 + const auto password = body.string("password").value_or("");
45 + if (!validatePassword(password, 12)) return badRequest("password is too short");
46 + return createUser(body);
47 }
• Ran make test && git diff --stat
└ {"stdout":"ok 1 - signup rejects a malformed email\nok 2 - signup rejects a short password\nok 3 - s
ignup accepts a valid payload\n3 tests, 0 failures\n src/handlers/signup.cpp | 6 +++++-\n tests/sign
up_test.cpp | 31 +++++++++++++++++++++++++\n 2 files changed, 36 insertions(+), 1 deletion(-)\n","stde
rr":"","exit_code":0}
• Added email and password validation to handleSignup. Invalid requests now get a 400
with a message, and passwords must be at least 12 characters.
Three new cases in tests/signup_test.cpp cover the rules; make test passes.
•◦Working ({{elapsed}}s • esc / ctrl + c to interrupt)
› Ask MicroCodex to do anything
gpt-6-sol · esc / ctrl + c interrupt ctrl + q quit gpt-6-sol · enter send ctrl + j newline ctrl + r reset ctrl + d quit
Binary
≈1 MB
Peak RSS
15–20 MB
Binary
≈1 MB
Peak memory
15–20 MB
Runtime
None, native C++23
Platforms
macOS · Linux
Footprint

Two orders of magnitude off your disk. One off your RAM.

Claude Code bundles a JavaScript runtime. Codex ships a large Rust binary. microcodex is plain native C++ that does one job well.

01{{unitLabel}}
{{b.name}}{{b.version}} {{b.value}}
02vs Codex CLI
281×
smaller binary
03vs Claude Code
224×
smaller install
02vs Claude Code
27×
less memory
03vs Codex CLI
16×
less memory
Ten microcodex sessions at peak use less memory than one average Claude Code session.
Agent Built with On disk Memory per session
microcodex Native C++23, no runtime ≈1 MB 15–20 MB peak
Claude Code TypeScript on a bundled Bun runtime 224 MB ~540 MB avg
Codex CLI Rust 281 MB ~315 MB avg

Sources. microcodex: the project’s own measurements of its release binary. Memory: average core process per session on macOS (Apple Silicon), Claude Code 2.1.285 and Codex CLI 0.155, from anthropics/claude-code#105268 (Codex measured with headless codex exec). Claude Code size: native install on Linux x64, v2.1.248, per Analytics India Magazine. Codex size: 280,704,736-byte binary, v0.169.0, per blueman82/muninn#93. Figures vary by version, platform and workload.

Features

A small binary, not a small agent

Everything you need for real work in a repo, without the weight you don’t.

01Interface

One-shot or interactive

Fire off a single prompt from a script or alias, or open the full terminal UI for a longer session.

$ microcodex "fix the failing date parser test"
› Ask MicroCodex to do anything
gpt-6-sol · enter send ctrl + j newline ctrl + r reset ctrl + d quit
$ microcodex "fix the failing date parser test"
› Ask MicroCodex to do anything
gpt-6-sol · enter send ctrl + j newline ctrl + r reset ctrl + d quit
02Effort

Reasoning effort, your call

Set --effort or MICROCODEX_EFFORT, sent in the same field the official Codex client uses.

03Context

Automatic compaction

Long sessions are compacted for you before they hit the context limit.

04Skills

Your Codex skills, reused

Discovers skills in $CODEX_HOME/skills, any folder with a SKILL.md.

~/.codex/skills/
├─ release-notes/SKILL.md
└─ migrations/SKILL.md
05Sign-in

Runs on your ChatGPT plan

OAuth sign-in, no API keys. Device auth for remote and headless machines.

microcodex loginbrowser
microcodex login --device-authheadless
06Sessions

Durable conversations

Conversations are kept, so work doesn’t vanish when the terminal does.

07Tools

Local coding tools

Read, write, edit, glob and bash, right where your code lives.

08Native

No runtime to install

No Node, no Bun, no node_modules. One file you can copy anywhere.

Install

Up and running in under a minute

Prefer a binary? Grab one from GitHub Releases. Building from source takes a C++23 compiler and make.

  1. 1Install

    Run the installer

    Pin a release with MICROCODEX_RELEASE.

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

    Use your ChatGPT plan

    Credentials stay in ~/.codex.

    microcodex login
  3. 3Run

    Ask for a change

    Run a one-shot prompt, or start the interactive UI.

    microcodex

Give your RAM back. Keep the agent.

One line to install. Apache-2.0, on macOS and Linux.

Read the source