Run a lightweight coding agent locally in your terminal

MicroCodex is an ultra-lightweight coding agent that runs locally in your terminal, written in C++23. It provides one-shot prompts, an interactive terminal UI, local coding tools, durable conversations, and automatic context compaction. After signing in with microcodex login, it authenticates against your ChatGPT plan via OAuth, storing credentials under $CODEX_HOME (or ~/.codex when unset), and can then run either as an interactive session or as a single one-shot prompt such as "Find the failing test, fix it, and run the relevant test suite."

Use MicroCodex when you want a minimal, fast, locally-run terminal coding agent backed by your existing ChatGPT plan rather than a heavier IDE-integrated tool. It is explicitly 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, but this guard is not a shell parser or a complete security boundary - commands that don't match the denylist, and all file operations, run with the same permissions as the MicroCodex process itself. It does not yet support MCP, and text cannot currently be copied from its terminal UI.

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

After installing, run microcodex login to authenticate (or microcodex login --device-auth on a remote or headless machine, entering a one-time code at a verification URL), then microcodex for an interactive session or microcodex "<prompt>" for a one-shot task. Prebuilt binaries for macOS (Apple Silicon and x86_64) and Linux (x86_64 and arm64) are attached to each GitHub Release; a specific version can be pinned by setting MICROCODEX_RELEASE before running the installer.

MicroCodex discovers the same filesystem skills installed for Codex under $CODEX_HOME/skills (or ~/.codex/skills): each skill needs a SKILL.md with YAML frontmatter containing a name and description, and its metadata is added to the agent's instructions at session startup, with the full skill body read only when its name or description matches the current task. Building from source requires a C++23 compiler, make, and libcurl 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, and make test runs the test suite. It is licensed under the Apache-2.0 License.

Developers who want a minimal, terminal-native coding agent that reuses their ChatGPT plan and existing Codex skills, without adopting a full IDE-integrated or sandboxed agent environment.