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 | shThen 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 shRun microcodex login and open the displayed URL in your browser. On a remote or headless machine, run microcodex login --device-auth and enter the displayed one-time code at the verification URL. 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. Before starting the user's shell, it applies a
simple lexical denylist that blocks forced file removal (rm -f/rm -rf),
git reset --hard, forced git clean, git checkout --, disk-formatting
tools, and shutdown commands. This guard is not a shell parser and is not a
complete security boundary: commands that do not match the denylist and all
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
makeThe 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.
- The bash safety gate is a lexical denylist, not a complete safe-command policy or sandbox; indirect or unrecognized destructive commands may not be blocked.
This repository is licensed under the Apache-2.0 License.