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 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.