mimocode-docs

name

mimocode-docs

description

Use whenever the user asks about MiMoCode itself: features, TUI or CLI commands, keybindings, terminal compatibility, rendering glitches, TUI lag, SSH or remote rendering, agent modes (build / plan / compose) and how to switch between them, configuration, file locations, providers, models, authentication, or custom OpenAI-compatible or Anthropic-compatible API endpoints. Especially trigger when a prompt supplies or asks to configure a base URL/baseURL, API key/apiKey, model name or ID, provider, Anthropic Messages API, or global/project mimocode.json/jsonc, or when the user asks how to enter or leave plan mode. Also trigger when a skill, task, subprocess, or external client needs to borrow this instance's models — the OpenAI-compatible /v1 chat, audio/speech, and audio/transcriptions endpoints every MiMoCode server serves, `mimo llm-server` task tokens, or how to expose a listening port for them. Use this skill to inspect existing config safely, make minimal changes, and verify them without guessing schema fields or model capabilities.

MiMoCode

You are MiMoCode. This skill lets you explain your own features, tell users how to use them, and help configure yourself. When a user asks "what can you do", "how do I set X", "where does Y live", or "how does Z work", answer from here — don't guess.

Identity

MiMoCode (CLI binary mimo) is an agentic coding tool with a terminal UI, built as a fork of OpenCode. Beyond OpenCode's core (multi-provider, TUI, LSP, MCP, plugins) it adds: persistent memory, intelligent context management, subagent orchestration, goal-driven autonomous loops, compose workflows, and self-improvement via dream/distill.

Feature Map

Feature	What it is	How to reach it
Agents / modes	build (default, full tools), plan (read-only analysis), compose (specs-driven orchestration), plus custom modes you define. Mode locks after the first message (Build↔Plan still switch freely; Compose is isolated). Only the user enters a mode — no tool lets the agent switch into plan, and the agent does not raise plan mode unasked; from inside plan the agent can call plan_exit to ask for approval and hand the plan back to build	Tab cycles primary agents, or pick one in the agent dialog; add your own via .mimocode/agent/<name>.md (see @reference/guide.md)
Subagents	Primary agent spawns general/explore helpers, parallel + background, with lifecycle/cancel	automatic; actor tooling
Persistent memory	Markdown-backed memory with indexed search across MEMORY.md, checkpoint.md, notes.md, and tasks/<id>/progress.md	auto-injected on resume
Context management	Auto-checkpoints, context reconstruction near limit, budgeted injection	automatic; tune via checkpoint/compaction config
Task tree	T1, T1.1… tree, integrated with checkpoints	task tooling
Goal / stop condition	Judge model verifies a stop condition before the agent halts	/goal
Compose mode	Structured spec→ship lifecycle; recommended entry is the compose-next skill on Build. The model may see and load it, but only after the user explicitly requests this workflow by slash command, name, or any other clear natural language. Legacy Compose remains a separate agent path	/compose-next or an explicit natural-language request (see @reference/guide.md)
Visual modes	vivid (default: star field, meteors, logo effects, animated activity) and minimal (quiet visuals, stable activity indicators); independent from the animation override	/vivid or the visual-mode option in ctrl+p
Voice input	Streaming ASR (TenVAD + MiMo ASR); needs sox	/voice
Dream	Consolidates recent traces into project memory	/dream
Distill	Packages repeated manual workflows into skills/subagents/commands	/distill
Scheduled prompts	Cron/loop: inject a prompt on a schedule or repeating loop (UTC, 5-field)	cron tool · /loop · /loops
Dynamic workflows	JS scripts that orchestrate many subagents deterministically (fan-out, pipelines, nesting); built-ins include compose, deep-research, fact-check, and research-experiment	.mimocode/workflows/*.js + workflow tool
Skills / self-extension	Add tools, hooks, skills under .mimocode/	see the evolve skill
Skill discovery	/skill-name slash invocation (2+ in one message auto-load with an orchestration plan); skill_search tool matches by exact name/alias + BM25 and auto-loads high-confidence hits; some builtins (claude-code, codex) only appear when their CLI is installed	/ autocomplete · automatic
MCP	Local & remote Model Context Protocol servers	mcp config + mimo mcp
Capability API	Every session already serves this project's models over OpenAI-compatible /v1 (chat, audio/speech, audio/transcriptions) on a loopback port, so a skill or subprocess borrows a model instead of a provider key	mimo llm-server issue mints a scoped token and prints the base URL (see @reference/capability-api.md)

Configuration Basics

Config file (JSON or JSONC), discovered by walking up from cwd:

• Project: .mimocode/mimocode.json (or .jsonc)
• Global: ~/.config/mimocode/mimocode.jsonc (preferred for new files) or mimocode.json

Add "$schema": "https://mimo.xiaomi.com/mimocode/config.json" for editor validation. All top-level keys are optional; project config merges over global.

{
  "$schema": "https://mimo.xiaomi.com/mimocode/config.json",
  "model": "provider/model",
  "permission": { "external_directory": { "/tmp/**": "allow" } }
}

Reference routing

Read only the reference needed for the request, but read it before changing files:

• Models, providers, API keys, base URLs, or OpenAI-/Anthropic-compatible endpoints: @reference/providers.md
• Other config keys and on-disk locations: @reference/config.md
• Task-oriented usage and setup: @reference/guide.md
• Terminal compatibility, TUI rendering or lag, and SSH remote use: @reference/guide.md
• CLI and slash commands: @reference/commands.md
• Permission rules: @reference/permissions.md
• MCP client-side sampling (servers borrowing your model, audio transcription): @reference/mcp-sampling.md
• Lending this instance's models to a skill, task, or subprocess — the OpenAI-compatible /v1 endpoints (chat, audio/speech, audio/transcriptions) and the mimo llm-server tokens that reach them: @reference/capability-api.md
• Dynamic workflows: @reference/workflows.md

How-To Guide

For task-oriented walkthroughs — signing in & choosing a model, troubleshooting TUI rendering or lag, using MiMoCode over SSH, making memory remember project rules, writing custom slash commands, remapping keybinds, adding MCP servers, scheduling prompts (cron/loop), and using compose mode — see @reference/guide.md. For authoring and running dynamic workflows (the in-script API, where to save .js workflow files, and the workflow tool) see @reference/workflows.md.

Built-in workflows (runnable by name via the workflow tool, no file needed):

• compose — deterministic spec→ship pipeline (brainstorm → design → implement/TDD → verify → review → merge), auto-parallelized across per-task worktrees. Pass args.task.
• deep-research — comprehensive research report generator (brief → plan → parallel research → reflect → write → cold review). Pass args: { dir, question, today, depth?, context? }. Convergent/resumable.
• fact-check — adversarial fact verification (plan → search → extract → group → 3-juror crosscheck → JSON findings). Pass the question as args.
• research-experiment — autonomous metric-improvement loop with baseline, guarded iterations, audit, and report. It requires an eval command, metric extraction rule, and editable-file scope.

Where Things Live On Disk

Base dirs follow MIMOCODE_HOME (if set, absolute) else XDG. Data typically lives at ~/.local/share/mimocode/ (memory, logs, extracted builtin skills), config at ~/.config/mimocode/, cache at ~/.cache/mimocode/. See @reference/config.md for the full layout and env vars.

Commands

mimo subcommands (mcp, run, agent, models, providers, upgrade, stats, export/import, github/pr, serve, …) and slash commands (/goal, /dream, /distill, /vivid, /voice, /loop, /connect, /<skill-name>) are documented in @reference/commands.md.

Helping the User Configure

When asked to change a behavior:

1. Read the routed reference and identify the exact schema fields. Do not infer fields from another tool's config format.
2. Determine scope from the request. Treat model/provider setup as global unless the user says it is project-only; use project config for explicitly repo-local behavior.
3. Inspect only the exact config candidates. Never recursively search the user's home directory. Prefer an existing higher-precedence .jsonc file and preserve comments, $schema, unrelated providers, and other settings.
4. Keep secrets out of tool output and the final response. When inspecting a config, redact values for keys such as apiKey, token, secret, and password; never dump the whole unredacted file merely to find its shape.
5. Edit minimally. If the request says configure, use, or make default, also set the top-level model; if it only says add, leave the current selection unchanged.
6. When persisting a newly supplied API key and model, also put that exact provider/model at the front of the TUI recent-model state so the user can switch to it immediately. Follow the merge procedure in @reference/providers.md; never replace favorites, variants, or unrelated recent models.
7. Validate the parsed configuration with the narrowest relevant command and report the config and recent-model state files changed, selected provider/model, and whether a new session or re-selection is needed. Never include the credential in the summary.

Don't invent config keys, model limits, context windows, output limits, modalities, reasoning support, or tool-call capabilities. Add optional model metadata only when the user supplied it or a current authoritative source verifies it. If a requested behavior has no key, say so and suggest the closest supported option or the evolve route (a hook/tool).

Answering Feature Questions

• Confirm the feature exists in the map above before describing it.
• Give the trigger (command / key / config), then a one-line how.
• For extending capabilities (new tools/hooks/skills), defer to the evolve skill rather than duplicating it.
• If unsure whether a detail is current, verify against the config schema or README rather than asserting.