A mekugi is the small peg that pins a Japanese sword's handle to the blade. Take it out and the handle comes off. Leave it in and the blade is still the blade.
Mekugi is a fast, source-grounded workspace for Codex. It keeps long sessions and multi-agent workflows lean, observable, and surgically reversible, while leaving Codex's editing, execution, sandbox, permissions, and config untouched.
Why Mekugi · Install · Quick start · Guides · Documentation
- Compaction that rereads real sources. Reset context without lossy LLM handover summaries. Agents select the exact files, skills, and captured changes needed for unfinished work, and Mekugi reloads them fresh before the next turn.
- Agent-chosen checkpoints & usage notices. Measured context-usage notices start at 50% and tell the agent to compact at 90%, so agents reset cleanly at safe checkpoints instead of drifting inside a bloated window.
- Built-in token-saving helpers. Wrapped sessions put
mcat(batched UTF-8 reads),mrun(head/tail-bounded commands),mread(exact continuation of omitted output),msymbol(Go, TypeScript, Python, and Rust semantic definitions/references), andinspect_file(structural outlines) onPATH. Automatic output deduplication replaces repeated outputs with compact references while keeping full results in history and the UI. - Workspace facts up front. Sessions start with an observed OS and Git snapshot and mark attached files and skills as reusable, cutting warm-up turns.
- Preloaded delegates. Fresh subagents start with selected files, skills, and captured changes already loaded under their own permissions, with no wasted first turns rediscovering parent context.
- Non-polling waits with progress check-ins. Parents wait for any or all descendants without polling loops. Optional progress yields pair brief developer status summaries with exact captured changes so coordinators catch wrong turns early.
- Side questions & isolated one-offs. Ask quick read-only questions with
/btwor spin up an isolated work-capable/oneoffbranch without polluting Main's transcript, and coordinate across active sessions.
- Every edit gets a short ID. Observed patches and shell writes are
captured as durable change IDs (
mchanges). Hand exact ranges (likeamber1..amber3) to reviewers or across compaction instead of dumping a noisy worktree diff mixed with your own edits. - Revert only what you reject. Undo specific captured edits (optionally
scoped to individual paths) with three-way merging that preserves your
uncommitted edits and other agents' work. Every revert is captured too and
can be reapplied anytime.
/rewindcan roll back conversation turns and their captured edits together.
- Watch edits stream live. Code changes stream into the Live Diff pane as the agent writes them. Operations appear under the reasoning that led to them, and the Agents sheet lets you inspect subagent transcripts, metrics, and steer them live.
- Intervene before mistakes land. Steer the running turn (
Enter), queue the next (Tab), interrupt (Esc), or inspect and stop one running command without killing the turn (/ps). - Remote-write &
sudoguards, even with--yolo. Interactive sessions prompt before supported Git, GitHub, Mercurial, SVN, and Jujutsu remote writes andsudocommands (requires unsandboxed execution; see Approvals and guards). - Private secrets, never in model context. Enter
sudopasswords and GPG passphrases (including Git signing) in a dedicated masked dialog that stays completely out of model input and session history. New or modified Codex hooks ask for trust before work starts.
- Detach without killing work. Sessions are owned by a local background server: close your terminal or browser and agents keep running. Reattach anytime from the terminal or control multiple machines from desktop or phone through the Web UI and authenticated connector.
- Full session lifecycle. Resume, fork, or rewind
sessions, inspect per-agent usage, throughput, and cost (
/session), replay past sessions offline, use reusable prompt presets, and connect custom OpenAI-compatible Responses providers.
Requirements:
- The managed native runtime, bundled in release archives and source builds.
Use Codex CLI directly for
codex login. - Built-in helpers need neither Node.js nor Bun. Semantic lookup (
msymbol) uses language servers on yourPATH; see Agent tools.
| Platform | Archive | Minimum OS |
|---|---|---|
| Linux x86-64 | mekugi_linux_amd64.tar.gz |
glibc 2.39 (e.g. Ubuntu 24.04) |
| Linux ARM64 | mekugi_linux_arm64.tar.gz |
glibc 2.39 (e.g. Ubuntu 24.04) |
| macOS Apple Silicon | mekugi_darwin_arm64.tar.gz |
macOS 15 |
Install mekugi, mekugi-exec, the native server, helpers, and model catalog
into ~/.local/bin (checksum-verified):
curl -fsSL https://raw.githubusercontent.com/yusing/mekugi/main/install.sh | shAdd ~/.local/bin to your PATH if needed. Release archives are also on
GitHub Releases (or from a
Build and release run). Non-glibc Linux environments (such as Alpine)
require a source build.
Requires Go 1.27+ (CGO enabled), a C/C++ toolchain, Make, Bun 1.4.4+, Node.js 24.21+, Python 3.11+, and Rustup. See native build dependencies for Linux libraries and the pinned Rust toolchain.
git clone https://github.com/yusing/mekugi.git
cd mekugi
git submodule update --init runtime/codex
make installAdd $GOBIN (or $(go env GOPATH)/bin) to your PATH. Run make uninstall
to remove installed executables and the bundled model catalog. Start a new
session after updating.
mekugi codex # Native OpenAI (uses `codex login`)
mekugi -p work # Custom Responses provider profilePut Mekugi flags before codex or Codex arguments. Bare mekugi requires
a custom provider profile.
Closing the UI leaves threads running and prints resume/replay commands. See
Launch and automation for headless runs and flags.
| To | Do |
|---|---|
| Steer the running turn / queue next | Enter / Tab |
| Interrupt | Esc |
| Show Main / toggle Diff / focus Agents | Ctrl-B, then 1 / 2 / 3 |
| Inspect or stop a running command | /ps |
| Ask a side question / run a one-off task | /btw, /oneoff |
| Compact, fork, or rewind | /compact, /fork, /rewind |
| Show all shortcuts | ? in an empty draft |
- Terminal UI: panes, composer, live diffs, Agents sheet, and output dialogs.
- Sessions and recovery: resume, fork, rewind, compaction, and replay storage.
- Agent tools and change review:
mcat,mrun,mread,msymbol,inspect_file, andmchanges. - Approvals and guards: Codex approvals, remote-write/sudo guards, and GPG passphrase entry.
- Server, connector and browser: remote control, browser UI, and Docker deployment.
- Providers: custom Responses providers.
- Launch and automation: launch options, execution policy, and headless runs.
- Configuration and metrics: settings file, flags, metrics, and integrations.
Product requirements and design · Documentation index · Contributing · Controlled comparisons · Codex end-to-end checks
For controlled comparisons against stock Codex, see codex-setup-ab.
MIT. See LICENSE.