@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 operator sessions for this repo
mu status                  # Show repository status
mu issues list             # List all issues
mu issues create "title"   # Create new issue
mu issues ready            # Show ready leaf issues
mu forum post topic -m "message"  # Post to forum
mu exec "task..."          # One-shot operator prompt
mu heartbeats --help        # Durable heartbeat automation programs
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.

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.

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

mu session list --json --pretty
mu turn --session-kind operator --session-id <session-id> --body "follow-up question"

If --session-kind is omitted, mu turn defaults to cp_operator (control-plane/operator-sessions) rather than terminal operator sessions.

In-session /mu helpers include:

• /mu hud ... (HUD surface for status/snapshot/on/off/toggle/clear/remove)
• /mu events ... (event tail/watch)
• /mu brand ... (chrome toggle)

Use mu store paths to resolve <store>, and mu control status to inspect current config-driven control-plane/operator state.

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 --pretty
mu store paths --pretty
mu control reload
mu control identities --all --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>/).