mu is a programmable personal assistant for technical work, designed for long-running execution, persistence, and reactivity.

Where other agents bake in complex logic, mu provides modular primitives (issue tracking, heartbeats, and programmable mu_ui docs) that agents orchestrate using shell commands. This makes mu highly customizable: as Mario and Armin note, bash is all you need.

Install mu globally via npm:

npm install -g @femtomc/mu

mu requires an AI model to function. Export your API key before starting. mu supports multiple models; export the one(s) you intend to use:

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-proj-..."
export GOOGLE_API_KEY="AIza..."
export OPENROUTER_API_KEY="sk-or-v1-..."

You can also auth with various providers. I would not recommend Google or Anthropic, because it is against their ToS and they will ban you -- OpenAI is the only provider which has condoned this (and GPT 5.3 is excellent):

mu login openai-codex

Start the mu server and attach a terminal operator session in your repository:

cd /path/to/your/repo
mu serve

In a separate terminal, use the CLI to interact with the assistant's state:

mu status --pretty
mu control harness --pretty
mu issues ready --pretty
mu forum post research:topic -m "found something" --author operator
mu memory search --query "reload" --limit 20

mu extends the pi framework with programmable batteries:

• CLI issue tracker & forum: Native tools to manage work and discussions (inspired by beads).
• Heartbeats & crons: Durable automation loops for long-running tasks (inspired by openclaw).
• Programmable UI (mu_ui): Real-time contextual status and interactive prompts published as UiDocs; this is the primary communication surface.
• Skill-based behavior: Customize agent workflows entirely through Markdown files.

Skills define the agent's behavior. Because mu relies on bash and CLI tools, you customize skills to change how mu works. mu ships with a hierarchy of version-synced starter skills bootstrapped into ~/.mu/skills/:

• Core (core): mu (CLI usage), programmable-ui (mu_ui/UiDoc workflows), memory (context retrieval), tmux (workspace fan-out), code-mode (REPL workflows)
• Subagents (subagents): planning (issue DAGs), protocol (shared DAG protocol), execution (durable orchestration runtime), control-flow (loop policies), model-routing (per-issue model/provider/thinking overlays)
• Automation (automation): heartbeats (lifecycle automation loops), crons (wall-clock scheduling)
• Messaging (messaging): setup-slack, setup-discord, setup-telegram, setup-neovim
• Writing (writing): writing (technical prose guidelines)

Usage pattern: Ask the agent to use a specific skill. For example: "Can we plan and setup an implementation issue DAG?" or "Set up the slack messaging service."

When names collide, mu loads the first match in this order:

1. Workspace: ~/.mu/workspaces/<workspace-id>/skills/
2. Global: ~/.mu/skills/
3. Repository: skills/
4. Pi framework (also loaded): .pi/skills/, ~/.pi/agent/skills/

mu supports native integrations via agent-first setup skills. The agent patches configuration, reloads the control plane, verifies capabilities, and guides you through required setup.

Manage the control plane with:

mu control status --pretty
mu store paths --pretty
mu control reload
mu control identities --all
mu control identities --all --json --pretty

Detailed adapter internals are available in the control-plane, server, and neovim package docs.

Manage interactive sessions using the CLI:

mu session list --json --pretty
mu session list --kind cp_operator --json --pretty
mu session list --kind all --all-workspaces --limit 50 --json --pretty
mu session <session-id>
mu turn --session-kind operator --session-id <session-id> --body "follow-up"

When installed from npm, READMEs exist at <mu-install>/node_modules/@femtomc/mu-<package>/README.md.

mu requires Bun for local development, while Node.js (npm) is sufficient for global runtime usage.

Set up the environment:

bun install
bun run check

Validate and test changes:

bun run guardrails:architecture
bun run guardrails
bun run typecheck
bun test
bun run fmt
bun run lint
bun run pack:smoke

Runtime state is strictly workspace-scoped. Data is stored under:

• ~/.mu/workspaces/<workspace-id>/
• or $MU_HOME/workspaces/<workspace-id>/

To find exact paths for the current repository:

mu store paths --pretty

To wipe the state for a specific project and start fresh, safely delete its workspace directory:

rm -rf ~/.mu/workspaces/<workspace-id>