mekugi

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 keeps stock Codex agents working from current, compact context across long sessions, compaction, and delegates, and lets you see what they are doing, what they are about to do, and what they have done. Codex keeps editing, execution, the sandbox, permissions, command sessions, and patch review. Invocation overrides leave Codex configuration unchanged.

Why Mekugi · Install · Quick start · Guides · Documentation

Why Mekugi

Agents work from current, compact context

• Compaction that rereads sources. Codex context resets without generating a handover summary. Agents can select files, skills and captured changes needed for unfinished work; Mekugi reads them before the conversation continues, so work resumes from current source text.
• Agent-chosen checkpoints. Agents can compact at safe checkpoints and continue, or compact while waiting for delegates. Measured usage reminders arrive from halfway full when usage is measured, with an instruction to compact at 90%. Early checkpoints can skip a costlier reset.
• Delegates start prepared. Fresh agents start with selected files, skills and captured changes already loaded. Parents wait for any or all current descendants without polling; optional progress yields pair developer summaries with captured changes to help catch mistakes before completion, rather than just checking liveness. Delegates can coordinate their own children and reply with a short summary and details. Assignments and messages can snapshot referenced files under the recipient's permissions, including when coordinating across sessions. Agents can also ask independent side questions without steering the recipient's work, and coordinate across active sessions.
• Facts up front. Codex agents receive an observed OS and Git snapshot, and attached files and skills are marked as reusable, so neither is rediscovered.
• Fewer output tokens, recoverable reads. Session helpers bound reads, symbol lookups, outlines and command output. Incomplete retained reads name their exact continuation; mrun discards output outside its selected window. Repeated output and supplied source bodies can become references to earlier visible text, and marked instruction blocks can be omitted. Full results stay in evidence and the UI.

Exact handoffs and undo

• Captured changes by ID. Every observed edit gets a short ID. Agents pass IDs and ranges to reviewers and across compaction, so a reviewer inspects exactly the delegated work rather than a worktree diff mixed with other agents' and your edits.
• Undo exactly what you reject. When you object to part of the work, the agent can revert the captured edits behind it, optionally limited to specific paths, without git restore. Later and unrelated edits, including your uncommitted work, are merged rather than discarded, and the revert can be reapplied. /rewind can also revert captured edits while removing an earlier turn and later conversation from the same session.

See what agents are doing, will do, and have done

• Live activity with its reasons. Operations appear under the reasoning that led to them. Delegates appear with their assignment and reply summary in Main, and with progress and metrics in the Agents pane. The roster identifies supported tool calls as their input is being generated, so a large call is less likely to look stalled. Open attachable children to read their transcripts and steer them.
• Catch mistakes before they land. Edits stream into the Diff pane while the agent writes them. Steer or interrupt the turn, stop one running command, or deny commands before they run.
• VCS remote-write and sudo guards. Approve or deny supported remote writes for Git, GitHub, Mercurial, SVN and Jujutsu, plus sudo commands, even with --yolo. Guards require interactive, unsandboxed execution and do not cover every way a program can perform a remote write.
• Private sudo passwords and GPG passphrases. Enter secrets in a dedicated dialog, not the conversation. Passwords and passphrases stay out of model input and retained history, including for Git signing.
• Hook trust prompts. Review and choose whether to trust new or changed Codex hooks before interactive work starts.
• Review what happened. Open saved edits by hunk, searchable per-command output, compaction events, and usage, throughput and cost. Missing evidence and provisional previews are labeled. Past sessions can be inspected or replayed.
• Herdr app panels. See the agent roster, saved changes and live edits in native Herdr panels that follow the active space, select an agent to switch its transcript and composer, and open file links or edit details in capable companion panels.

Work from anywhere

• Server-owned threads. Threads keep running when the terminal or browser closes. Control them from another machine, including phones, through an authenticated connector.
• Session continuity. Resume, fork, or rewind conversations.
• Providers and delegates. Use Grok, OpenCode Go and Zen, and Claude delegates through the same coordination tools.
• Composer. Attach files and skills, ask side questions, run one-off tasks, recall presets, and change model, reasoning, tier and permissions in session. See the composer.

Savings from bounded output, deduplication and source reloads don't guarantee better results on every task. For controlled comparisons, use codex-setup-ab. The product principles explain these choices.

Install

Requirements:

• Codex CLI on the execution machine.
• Built-in helpers need neither Node.js nor Bun; semantic lookup uses the language servers listed in agent tools.
• Any interpreter your agent picks, such as python3, on the executor's PATH.
• Claude delegates additionally need Bun and an authenticated Claude Code installation on the execution machine's PATH.

Release binaries

Platform	Archive	Minimum OS
Linux x86-64	mekugi_linux_amd64.tar.gz	glibc 2.39, such as Ubuntu 24.04
Linux ARM64	mekugi_linux_arm64.tar.gz	glibc 2.39, such as Ubuntu 24.04
macOS Apple Silicon	mekugi_darwin_arm64.tar.gz	macOS 15

The installer selects your platform, verifies the release checksum, and installs mekugi and mekugi-exec into ~/.local/bin, replacing existing copies:

curl -fsSL https://raw.githubusercontent.com/yusing/mekugi/main/install.sh | sh

Add ~/.local/bin to your PATH if needed. Archives are also on GitHub Releases; they need no Go or C toolchain. Linux releases need glibc and do not run on stock Alpine Linux; use a source build for other environments.

Build from source

Source installs require Go 1.27+, CGO enabled, a C toolchain, Make, Bun 1.4.4+, and Node.js 24.21+ for browser assets:

git clone https://github.com/yusing/mekugi.git
cd mekugi
make install

Add $GOBIN, or $(go env GOPATH)/bin if that is unset, to your PATH. make uninstall removes only the two binaries. Running sessions keep their worker executable, so start a new session to pick up an update.

Quick start

mekugi codex                    # Codex models, using `codex login`
mekugi grok -m grok-4.7         # Grok credentials
mekugi -m opencode-go:glm-5.3   # OpenCode credentials

Mekugi flags go before codex, grok, or Codex arguments. The launch starts a local server when needed and attaches the terminal UI. Closing the UI leaves the thread running; exit prints resume and replay commands. Codex's approval and sandbox policy applies; the remote-write guard needs unsandboxed execution. Mekugi needs Codex's JavaScript exec; custom inference endpoints and --oss are unsupported. See launch details.

To	Do
Steer the running turn / queue for the next	Enter / Tab
Interrupt	Esc
Show Main / toggle Diff / focus Agents	Ctrl-B, then 1 / 2 / 3
See running commands and stop one	/ps
Compact, fork, or rewind	/compact, /fork, /rewind
Show shortcuts	? in an empty draft

Guides

• Terminal UI: panes, composer, live diffs, Agents pane, output dialogs and optional Herdr app panels.
• Sessions and recovery: resume, fork, rewind, compaction and replay storage.
• Agent tools and change review: mcat, mrun, mread, msymbol, inspect_file and mchanges.
• Approvals and guards: Codex approvals, remote-write/sudo guards and secure GPG passphrase entry.
• Server, connector and browser: remote control, browser UI and Docker deployment.
• Providers and delegates: Grok, OpenCode and Claude delegates.
• Launch and automation: launch commands, execution policy and headless runs.
• Configuration and metrics: settings file, options, metrics and troubleshooting.

Documentation

Product intent and design · Documentation index · Contributing · Comparisons · Codex end-to-end checks

License

MIT. See LICENSE.