microcodex

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 32 Open GitHub ↗

MicroCodex is an ultra-lightweight coding agent that runs in your terminal

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

MicroCodex is an ultra-lightweight coding agent that runs locally in your terminal.

 <img src="assets/microcodex-splash-1.png" alt="MicroCodex splash" width="60%" />


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:

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

<details>
<summary>You can also go to the <a href="https://github.com/paoloanzn/microcodex/releases/latest">latest GitHub Release</a> and download the appropriate binary for your platform.</summary>

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.

</details>

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`:

```shell
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:

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

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

```shell
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](https://github.com/paoloanzn/microcodex/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**](#using-microcodex-with-your-chatgpt-plan)
- [**Installing & building**](#installing-and-running-microcodex)
- [**Tests**](tests/TESTS.md)

This repository is licensed under the [Apache-2.0 License](LICENSE).

microcodex

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README