paoloanzn/microcodex

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.

---

Quickstart

Installing and running MicroCodex

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.

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

Using MicroCodex with your ChatGPT plan

Run 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"

To choose how hard the model thinks, pass --effort or set MICROCODEX_EFFORT (the flag wins when both are given):

microcodex --effort high "Find the failing test, fix it, and run the relevant test suite"

Accepted values are none, minimal, low, medium, high, xhigh, max, ultra, and persistent; the default is medium. Empty or unknown values are rejected with an error. The value is sent to the API as the request’s reasoning.effort field, the same field the official Codex client uses.

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

Using Codex skills

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 from source

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.

Known bugs and issues

• View all issues
• 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.

Docs

• CLI usage
• Installing & building
• Tests

This repository is licensed under the Apache-2.0 License.