paoloanzn/microcodex
MicroCodex is an ultra-lightweight coding agent that runs in your terminal - paoloanzn/microcodex
3 stars · 0 forks · 0 watchers
README
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.
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
Linux
x86_64: microcodex-x86_64-unknown-linux-gnu.tar.gz arm64: microcodex-aarch64-unknown-linux-gnu.tar.gz
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 Using MicroCodex with your ChatGPT plan 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" WarningMicroCodex is not a sandbox. Model-requested commands and 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
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.
Docs
CLI usage Installing & building Tests
This repository is licensed under the Apache-2.0 License.