GitHub - ylxdzsw/mu: [vibed project] Small composable agent runtime for the terminal

mu is a small, composable agent for the terminal: read one prompt from stdin, write outputs to stdout, then exit. All state is persisted in append-only session logs.

Actual CLI mu lives in your shell as a shell mode (currently supports zsh and fish). Press Tab to switch between normal shell mode and mu mode. In mu mode, the prompt is send to mu instead of being interpreted as shell commands. You can literally find all executed mu commands in .zsh_history, just like normal shell commands.

Standard Shell Interaction Each prompt is executed by an ordinary mu process. All normal shell interactions just work: Ctrl+Z to suspend, fg to resume, resizing without refreshing, scrollback with interleaved shell history and mu history, and whatever cursor movement keybindings you configured for your shell. mu is in your shell, after all.

Absolute Minimum Toolset mu comes with only one tool: bash. That's 75% fewer than pi.

"Code Mode" If you doubt how a single bash suffices: this idea is closely related to code mode. The difference is that we choose bash, a language with battle-tested composability and conciseness, over javascript, and we use POSIX tools, the common denominator across agents that all models are born to master, instead of a custom tool set. Since POSIX commands need no teaching, the total system prompt of mu is < 1k tokens.

"Applets" apply_patch, edit, and view_image are provided as "applets" (symlinks to mu that dispatch based on argv[0]), as a workaround for reliable file editing without escaping (with the stdin argument of the bash tool) and taking multi-modal inputs.

Advisory Risk Labeling The bash tool requires the model to label every invocation as readonly, reversible, or destructive. It affects concurrent execution and retry (readonly calls are run in parallel and can auto retry), as well as trapping (destructive actions pause the execution by default).

Shebang Support Add #!/usr/bin/env mu to reusable prompt files to run them as regular commands. To specify a model, use #!/usr/bin/env -S mu --model <model-ref>. Other options, such as session selection, belong on the command line, not in the shebang.

Skill System Skills are prompt files that auto loaded on demand by the agent, indicated by front matter. They can coexist with shebang, allowing a prompt file both manually invocable and automatically loadable.

Multi-provider Supports Chat Completion, Responses, and Anthropic Messages APIs, with optional automatic fallback. Common quirks, like cache keys, opaque reasoning replay, context length errors, etc. are handled properly.

Stateless mu processes are short-lived: they exit after processing one prompt. The shell tracks only a session id, as a plain string in $MU_SESSION_ID. Memory leaks are eliminated entirely. mu also supports transparent mu retry, that resends a request to LLM without an extra "continue" user message.

Cache Friendly mu session history is strictly append-only. Refreshing of AGENTS.md or skill catalog only happens after compaction.

Compaction mu has two compaction thresholds: the soft threshold triggers before a new turn's first provider request, while the hard threshold triggers during a turn after tool results. Provider context length errors can also trigger emergency compaction.

Simple Installation mu is one single statically linked binary plus one single-file shell plugin. It can be droped anywhere and run.

Quick start

On Linux x86-64, download the latest portable binary and put it on PATH:

mkdir -p "$HOME/.local/bin"
curl -fsSL https://github.com/ylxdzsw/mu/releases/latest/download/mu-linux-x86_64-musl -o "$HOME/.local/bin/mu"
chmod +x "$HOME/.local/bin/mu"
export PATH="$HOME/.local/bin:$PATH"

MacOS binaries and ArchLinux package are available at releases.

Now ask it something:

mu <<< 'Introduce yourself. Including CLI usage and configuration guide.'

Out of the box mu bundles a free model from OpenCode Zen, so you can try it immediately without configuring anything.

The intended way to use mu is through the shell plugins. For zsh:

source <(curl -fsSL https://github.com/ylxdzsw/mu/releases/latest/download/mu.zsh)

(This loads the plugin in your current session and modifies nothing on the machine.)

For Fish 4 or newer:

curl -fsSL https://github.com/ylxdzsw/mu/releases/latest/download/mu.fish | source

At an empty shell prompt, press Tab to enter mu> mode, type a request, and press Enter:

mu> what changed in the last three commits?

Type / to list prompt-mode commands. The common ones:

/new starts a new session while keeping the current model and trap level.
/load [<session-id>] renders an existing session's transcript and attaches the shell to it for later turns. Without an id, it loads the active scope's last selected session. It uses the current output density.
/model selects a configured model for later turns in this shell scope. Use Tab to auto complete the provider, model name, and effort levels.
/trap <off|destructive|reversible|all> persistently selects the Bash trap level for this shell scope. /trap default returns to configuration.
/retry resumes a turn interrupted by Ctrl-C, a crash, a lost connection, or exhausted automatic resume attempts.
/compact checkpoints a long session through a synthetic summary turn, optionally with a focus instruction.
When soft_interrupt is enabled (the default), press Ctrl+\ while Mu is working to stop at the next safe boundary (steering).

Sharing mu's context with other agents

mu context --export emits mu's context for a foreign agent: it includes a short preamble, the effective AGENTS.md, and mu's skills. It can be given to other agents as instruction files.

For Codex, add a SessionStart hook at ~/.codex/hooks.json:

{
  "description": "Load mu instructions and skills.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|compact",
        "hooks": [{ "type": "command", "command": "mu context --export", "timeout": 10, "statusMessage": "Loading mu context" }]
      }
    ]
  }
}

For Claude Code, add a SessionStart hook to ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "mu context --export" }] }
    ]
  }
}

Complete Guide

Read the shipped CLI reference and configuration and skills guide. The Mu documentation skill points the agent to these references.

Run this command to get an up-to-date, complete, and example-rich guide:

mu <<< 'Find and read your source code on GitHub, then give me a complete guide for your usage, covering all aspects in detail, with plenty of examples.'