Mira API Docs

Mira Code Configuration

Mira Code can be configured at multiple levels: globally, per-project, and through instruction files. This page covers all configuration options and their precedence.

Configuration Precedence

When the same option is specified in multiple places, Mira Code uses the following precedence order (highest to lowest):

Precedence order
1. CLI flags              (--model mira-pro)
2. Environment vars       (MIRA_MODEL=mira-pro)
3. Project local settings (.mira/settings.local.json)
4. Project settings       (.mira/settings.json)
5. Global config          (~/.mira.json)
6. Default values
This means a --model flag will always override a value from settings.json or the MIRA_MODEL environment variable.

Global Configuration

Global configuration applies to all projects and is stored in the user's home directory:

~/.mira.json
{
  "model": "mira",
  "maxTokens": 4096,
  "theme": "dark",
  "permissions": {
    "fileRead": "auto",
    "fileWrite": "ask",
    "commandExecution": "ask"
  },
  "telemetry": false,
  "editor": "code",
  "shell": "/bin/zsh"
}

This file is created automatically on first launch. You can edit it with any text editor.

Project Settings

Project settings are stored in .mira/settings.json in the project root. They override global settings:

.mira/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(npm test:*)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "MIRA_MODEL": "mira-pro"
  }
}

For private settings, use .mira/settings.local.json (add to .gitignore):

.mira/settings.local.json
{
  "env": {
    "MIRA_API_KEY": "sk-mira-your-personal-key"
  }
}
Commit .mira/settings.json to version control so all team members share the same settings. Keep settings.local.json in .gitignore.

Instruction Files (MIRA.md)

Mira Code supports MIRA.md files for storing project-specific instructions. These files are written in Markdown and loaded automatically at startup:

MIRA.md
# Project Instructions

## Code Style
- Use functional components with TypeScript
- Prefer named exports over default exports
- Use Tailwind CSS for styling — no CSS modules
- All components must have proper TypeScript interfaces

## Architecture
- Follow the App Router pattern (Next.js 14+)
- Server components by default, "use client" only when needed
- Data fetching in server components, not in client components

## Testing
- Write tests for all utility functions
- Use Vitest + React Testing Library
- Minimum 80% coverage for new code

## Git
- Use conventional commits (feat:, fix:, chore:, etc.)
- Keep commits atomic — one logical change per commit

Mira Code looks for instruction files in the following order:

  • MIRA.md — In project root (recommended)
  • .mira/MIRA.md — In the project .mira directory
  • .mira/rules/*.md — Rules in the .mira/rules directory
  • MIRA.local.md — Private instructions (add to .gitignore)

Themes and Appearance

Mira Code supports two display themes:

ThemeDescription
darkDark theme (default). Optimized for dark terminal backgrounds.
lightLight theme. Optimized for light terminal backgrounds.
Setting the theme
// In ~/.mira.json
{
  "theme": "light"
}

// Or via environment variable
export MIRA_THEME="light"

Model Selection

Mira Code supports multiple AI models. Available models are fetched dynamically from the vmira.ai platform:

ModelDescriptionBest for
miraFast, general purposeEveryday tasks
mira-proAdvanced capabilities + thinking modeArchitecture decisions, complex logic, debugging
mira-maxMaximum performance + thinking modeLarge-scale refactoring, codebase analysis
Ways to select a model
# CLI flag (highest priority)
mira --model mira-pro

# Environment variable
export MIRA_MODEL="mira-pro"

# In .mira/settings.json
{ "env": { "MIRA_MODEL": "mira-pro" } }

# Interactive: use /model command
> /model

Permission System

Mira Code uses a tool-based permission system. Each tool (Read, Edit, Write, Bash, etc.) can be allowed or denied in project settings:

.mira/settings.json
{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Write",
      "Bash(npm test:*)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Bash(rm -rf *)"
    ]
  }
}

By default, Mira Code asks for confirmation before writing files and running commands. File reads are allowed automatically.

The --yolo flag disables all confirmations. Mira Code will automatically edit files and run commands without your approval. Use only in isolated development environments.