@femtomc/mu

mu is a personal assistant for technical work.

This package provides the Bun CLI and programmatic API.

Install

After publishing:

npm install -g @femtomc/mu
# or: bun add -g @femtomc/mu

From this repo:

cd mu
bun install
bun run build
packages/cli/dist/cli.js --help

Usage

CLI Commands

mu serve                   # Start server + terminal operator session (auto-inits workspace store)
mu session                 # Reconnect to latest persisted operator session
mu session list            # List persisted sessions (operator + cp_operator) for this repo
mu session list --kind all --all-workspaces --limit 50
mu session list --verbose  # Show per-row kind chips in text output (op/cp)
mu status                  # Compact repository status summary
mu status --verbose        # Expanded ready/topic detail
mu control harness         # Compact harness adapter/provider/model snapshot
mu control harness --verbose  # Expanded capability vectors
mu control config get      # Compact typed workspace control-plane config
mu control config get --verbose  # Include defaults + descriptions
mu control ui-state list   # Inspect persisted UiDoc scope/revision snapshots
mu issues list --limit 20  # List recent issues (use --all for unbounded)
mu issues create "title"   # Create new issue
mu issues ready            # Show ready leaf issues
mu issues close <id> --allow-heartbeat-managed  # Override heartbeat ownership guardrails when needed
mu forum post topic -m "message"  # Post to forum
mu exec "task..."          # One-shot operator prompt
mu heartbeats --help        # Durable heartbeat automation programs
mu heartbeats stats         # Heartbeat scheduler summary (total/enabled/armed)
mu heartbeats create --title "Watchdog" --provider openrouter --model google/gemini-3.1-pro-preview --thinking high
mu heartbeats update hb-123 --session-id checkpoint-hb-123 --session-file .mu/control-plane/operator-sessions/checkpoint.jsonl
mu cron --help              # Durable cron automation programs

Most issue/forum/event/control-plane read surfaces now default to compact output. Use --json (optionally with --pretty) when you need full machine records.

Use mu exec when you want a lightweight one-shot operator response. Use mu heartbeats/mu cron + mu turn/mu session for durable operator-centric automation loops.

Heartbeat programs can now carry per-program model routing and context checkpoints:

• --provider/--model/--thinking set the autonomous operator profile for that heartbeat.
• --session-id pins heartbeat wakes to a stable autonomous session identity.
• --session-file / --session-dir let heartbeats resume from explicit persisted checkpoints.

Memory retrieval supports a local memory index:

mu memory index status
mu memory index rebuild
mu memory search --query "reload" --limit 20

When the index exists, mu memory search|timeline|stats run index-first with automatic fallback to direct JSONL scans. When the index is missing, memory queries auto-heal it on demand, and mu serve performs scheduled stale-index maintenance.

Programmatic API

import { run } from "@femtomc/mu";

const r = await run(["status", "--json"]);
if (r.exitCode !== 0) throw new Error(r.stdout);
console.log(r.stdout);

Serve + terminal operator

The mu serve command starts the server and immediately attaches an interactive terminal operator session in the same shell:

mu serve              # Default port: 3000 (operator session)
mu serve --port 8080  # Custom port

Type /exit, Ctrl+D, or Ctrl+C to leave the operator session. The server keeps running in the background; use mu stop to shut it down.

In headless environments, use SSH port forwarding as needed.

Operator session defaults

mu serve's attached terminal operator session inherits <store>/config.json defaults from control_plane.operator.provider/model when present. The session uses generic tools and invokes mu CLI commands directly for reads and mutations.

By default, operator sessions are persisted under <store>/operator/sessions, and mu session reconnects to the latest persisted session. mu session list defaults to both session kinds (operator + cp_operator). Text list output is compact by default; use --verbose to include kind chips and per-row session paths.

For follow-up handoffs on a prior terminal/tmux session:

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>  # auto-resolves operator/cp_operator stores by id
mu turn --session-kind operator --session-id <session-id> --body "follow-up question"

Session-scoped model/thinking updates (without changing workspace global defaults):

mu session config get --session-id <id>
mu session config set-model --session-id <id> --provider openai-codex --model gpt-5.3-codex --thinking high
mu session config set-thinking --session-id <id> --thinking minimal

Workspace global defaults remain under:

mu control operator set <provider> <model> [thinking]
mu control operator thinking-set <thinking>

Additional typed workspace config controls:

mu control config get
mu control config set control_plane.operator.enabled false
mu control config set control_plane.memory_index.every_ms 120000
mu control config unset control_plane.adapters.slack.bot_token

If --session-kind is omitted, mu turn auto-resolves --session-id across both session stores (operator/sessions + control-plane/operator-sessions). If the same id exists in both, pass --session-kind (or --session-dir) to disambiguate.

In-session /mu helpers include:

• /mu ui status / /mu ui snapshot [compact|multiline] (primary mu_ui status inspection surface)
• /mu events ... (event tail/watch)
• /mu brand ... (chrome toggle)

Use mu store paths to resolve <store>, mu control status for compact control-plane/operator state (or --verbose for detail), and mu control harness for compact provider/model availability + capability vectors (--verbose to expand).

Messaging setup (skills-first)

Prefer bundled setup skills for channel onboarding (setup-slack, setup-discord, setup-telegram, setup-neovim). These workflows are agent-first: the agent patches config, reloads control-plane, verifies routes/capabilities, and asks the user only for required external-console steps and secret handoff.

Baseline control-plane commands:

mu control status
mu control status --verbose
mu control config get
mu control config get --verbose
mu store paths --pretty
mu control reload
mu control identities --all
mu control identities --all --json --pretty

For manual linking (Slack/Discord/Telegram):

mu control link --channel slack --actor-id U123 --tenant-id T123
mu control link --channel discord --actor-id <user-id> --tenant-id <guild-id>
mu control link --channel telegram --actor-id <chat-id> --tenant-id telegram-bot

For Neovim identity binding, use :Mu link from mu.nvim.

Tests / Typecheck

From the mu/ repo root:

bun test packages/cli
bun run typecheck

Runtime

• Bun runtime (ESM).
• Reads/writes workspace-scoped state under ~/.mu/workspaces/<workspace-id>/ (or $MU_HOME/workspaces/<workspace-id>/).