mimo-code

English  ·  简体中文  ·  日本語

A CLI coding agent powered by the MiMo large language model.

Built with TypeScript and Ink — your AI pair programmer that lives in the terminal.

Overview

Mimo Code is a terminal-based AI coding assistant that brings the power of the MiMo large language model to your development workflow. Built with TypeScript and Ink (React for CLI), it provides an interactive REPL where you can write code, execute commands, search files, and manage tasks — all through natural language conversation.

✨ Features

🛠️ 13 Built-in Tools

🔌 Multi-Provider API Support

• MiMo — Native support with 1M context window and automatic compression. Models: mimo-v2.5-pro (1T params, $1-2/M input), mimo-v2.5 ($0.40-0.80/M input)
• OpenAI — Full OpenAI-compatible API with streaming SSE
• Anthropic — Direct Claude API integration

🎨 Additional Capabilities

• Rich Terminal UI — React-based REPL with syntax highlighting, diffs, and progress indicators
• Markdown Rendering — Headers, bold text, tables, and inline code rendered in terminal
• Multi-language UI — Switch between 简体中文, English, 日本語 via /language command
• Xiaomi Cat Mascot — Animated ASCII companion that reacts to agent state (idle → thinking → coding → success/error)
• Permission System — 5 modes: default, acceptEdits, bypassPermissions, plan, auto
• Plugin System — Event-driven architecture with EventBus and plugin discovery
• MCP Client — Model Context Protocol support via JSON-RPC 2.0 over stdio
• Slash Commands — 15+ commands for session control, model switching, and diagnostics
• Theme System — 5 built-in themes: mimo-dark, mimo-light, dracula, nord, solarized-dark
• Multi-mode Execution — Interactive REPL, single-shot prompts, and pipe mode

🚀 Quick Start

Prerequisites

• Node.js ≥ 18
• npm or yarn
• A MiMo API key (or OpenAI/Anthropic key)

Install

git clone https://github.com/raaaaap/mimo-code.git
cd mimo-code
npm install
npm link          # Register 'mimo' command globally

Configure

Option A: Environment variable

export MIMO_API_KEY=your-api-key-here

Option B: Settings file

Create ~/.mimo/settings.json:

{
  "model": "mimo-v2.5",
  "apiKey": "your-api-key-here",
  "apiEndpoint": "https://api.mimo.ai/v1"
}

Option C: Interactive setup — Mimo Code will prompt you on first run.

Run

# After npm link, use the 'mimo' command directly
mimo

# With options
mimo --theme dracula --model mimo-v2.5

# Development mode (with hot reload)
npm run dev

# Or run without global link
node bin/mimo.js --theme dracula

📖 Usage

CLI Options

mimo [options] [prompt]

Options:
  -m, --model <model>          Model to use (default: "mimo-v2.5")
  -k, --api-key <key>          API key
  --api-endpoint <url>         API endpoint URL
  --mode <mode>                Mode: interactive, single, pipe (default: "interactive")
  -v, --verbose                Verbose output
  --debug                      Debug mode
  -o, --output <format>        Output format: text, json, markdown
  --no-color                   Disable colors
  --theme <theme>              UI theme: mimo-dark, mimo-light, dracula, nord, solarized-dark
  --max-tokens <n>             Max tokens (default: 8192)
  --temperature <n>            Temperature (default: 0.7)
  --permission-mode <mode>     Permission mode: default, acceptEdits, bypassPermissions, plan, auto
  -h, --help                   Display help
  -V, --version                Display version

Execution Modes

# Interactive REPL (default)
mimo

# One-shot prompt
mimo --mode single "Explain the use of React hooks"

# Pipe mode (read from stdin)
echo "What does this code do?" | mimo --mode pipe
cat main.ts | mimo --mode pipe "Explain this file"

Slash Commands

Keyboard Shortcuts

🏗️ Architecture

src/
├── entrypoints/       # CLI entry points (cli.tsx, init.ts, mcp.ts)
├── main.tsx           # Commander CLI setup, mode dispatch
├── query.ts           # Core agent loop (async generator)
├── QueryEngine.ts     # Conversation lifecycle manager
├── context.ts         # System context gathering (git, cwd, date)
├── screens/           # REPL screen (React/Ink)
├── components/        # UI components
│   ├── Messages/      # Conversation rendering
│   ├── PromptInput/   # User input handling
│   ├── Mimo/          # Avatar display
│   ├── StructuredDiff/# Diff visualization
│   ├── HighlightedCode/# Syntax highlighting
│   └── design-system/ # Button, Card, Table primitives
├── tools/             # 13 built-in tool implementations
├── services/
│   ├── api/           # API client + adapters (OpenAI, Anthropic, MiMo)
│   ├── tools/         # Tool execution engine & orchestration
│   ├── permissions/   # Permission checker (5 modes)
│   ├── mcp/           # MCP client (JSON-RPC 2.0 over stdio)
│   └── lsp/           # LSP client (stub)
├── plugins/           # EventBus + PluginManager + loader
├── commands/          # 15+ slash commands
├── skills/            # Skill system (remember, simplify)
├── buddy/             # Xiaomi Cat mascot (animated ASCII art)
├── state/             # Custom state store
├── utils/
│   ├── settings/      # Layered config (user → project → local → flags)
│   └── themes.ts      # 5 built-in themes
├── modes/             # single.ts, pipe.ts
├── hooks/             # Hook registry
├── keybindings/       # Key binding parser
├── history/           # Conversation history store
├── session/           # Session persistence
├── tasks/             # Task manager
├── telemetry/         # Usage telemetry
└── vim/               # Vim mode state

Query Loop

The heart of Mimo Code is the query loop (query.ts):

User Input → System Prompt + Context → API Request (streaming)
    ↓
Text chunks → Display in terminal
Tool calls → Execute via ToolRegistry → Append results → Loop
    ↓
(max 20 turns or until no more tool calls)

Tools are orchestrated intelligently: concurrency-safe tools (read-only) run in parallel, while destructive tools run sequentially with permission checks.

⚙️ Configuration

Settings Hierarchy

Settings are merged from four sources (highest priority first):

1. CLI flags — --model, --api-key, etc.
2. Local settings — .mimo/settings.local.json (gitignored)
3. Project settings — .mimo/settings.json
4. User settings — ~/.mimo/settings.json

Environment Variables

Permission Modes

🧪 Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

# Type checking
npm run typecheck

# Linting
npm run lint

The project includes 62 test files covering:

• Unit tests for all 13 tools
• API adapter tests (OpenAI, Anthropic, MiMo)
• Query engine and conversation flow tests
• Plugin, permission, and settings system tests
• Integration tests for agent conversation flows

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'feat: add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

git clone https://github.com/raaaaap/mimo-code.git
cd mimo-code
npm install
npm run dev

Commit Convention

This project follows Conventional Commits:

• feat: — New features
• fix: — Bug fixes
• docs: — Documentation changes
• refactor: — Code refactoring
• test: — Test additions or changes
• chore: — Build/tooling changes

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.