Config File

Magic Shell stores configuration in ~/.magic-shell/config.json.

Location

Platform	Path
macOS	~/.magic-shell/config.json
Linux	~/.magic-shell/config.json
Windows	%USERPROFILE%\.magic-shell\config.json

Default Configuration

{
  "provider": "opencode-zen",
  "defaultModel": "deepseek-v4-flash-free",
  "thinkingLevel": "low",
  "safetyLevel": "moderate",
  "dryRunByDefault": false,
  "cloudflareAccountId": "",
  "cloudflareAiGatewayId": "default",
  "repoContext": false,
  "theme": "opencode",
  "blockedCommands": [],
  "confirmedDangerousPatterns": [],
  "customModels": []
}

Options Reference

provider

The AI provider to use for translations.

Value	Description
"opencode-zen"	OpenCode Zen (default)
"openrouter"	OpenRouter
"vercel-ai-gateway"	Vercel AI Gateway
"cloudflare-ai-gateway"	Cloudflare AI Gateway
"workers-ai"	Cloudflare Workers AI
"custom"	Custom OpenAI-compatible endpoint

{
  "provider": "opencode-zen"
}

defaultModel

The model ID to use for translations.

{
  "defaultModel": "deepseek-v4-flash-free"
}

Run msh --models to see available models for your provider.

provider API key fallbacks

Provider API keys are stored in your system keychain when secure storage is available. If keychain storage is unavailable, Magic Shell can use these config fields as fallbacks:

Field	Provider
opencodeZenApiKey	OpenCode Zen
openrouterApiKey	OpenRouter
vercelAiGatewayApiKey	Vercel AI Gateway
cloudflareAiGatewayApiKey	Cloudflare AI Gateway
workersAiApiKey	Cloudflare Workers AI

Environment variables take precedence over both keychain and config-file values.

cloudflareAccountId

Cloudflare account ID used by Cloudflare AI Gateway and Workers AI.

{
  "cloudflareAccountId": "your-account-id"
}

cloudflareAiGatewayId

Cloudflare AI Gateway ID. Defaults to default.

{
  "cloudflareAiGatewayId": "default"
}

thinkingLevel

Controls provider thinking/reasoning depth for supported models.

Value	Description
"off"	Do not request provider thinking controls
"low"	Low-cost reasoning (default)
"medium"	More reasoning for harder translations
"high"	Maximum reasoning for supported models

{
  "thinkingLevel": "low"
}

safetyLevel

Controls when commands require confirmation.

Value	Description
"strict"	Confirm all potentially risky commands
"moderate"	Confirm high and critical severity (default)
"relaxed"	Only block critical severity

{
  "safetyLevel": "moderate"
}

dryRunByDefault

When true, always show commands without executing them.

{
  "dryRunByDefault": false
}

repoContext

When true, Magic Shell detects your project type and available commands. This sends minimal, non-sensitive information (script names, not contents) to the AI for better context.

Detected project types:

• Node.js: Reads package.json scripts and detects package manager (npm, bun, yarn, pnpm)
• Makefile: Extracts make targets
• Rust: Knows standard cargo commands
• Python: Detects pyproject.toml, setup.py, requirements.txt
• Go: Detects go.mod

{
  "repoContext": true
}

Enable via CLI:

msh --repo-context   # Enable permanently
msh -r "run tests"   # Use for single command

theme

Color theme for TUI mode and CLI output.

Available themes:

• "opencode" (default)
• "tokyonight"
• "catppuccin"
• "gruvbox"
• "nord"
• "dracula"
• "one-dark"
• "matrix"

{
  "theme": "opencode"
}

blockedCommands

Array of command patterns to always block.

{
  "blockedCommands": [
    "DROP TABLE",
    "TRUNCATE",
    "format c:"
  ]
}

confirmedDangerousPatterns

Patterns you’ve previously confirmed as safe for your use case.

{
  "confirmedDangerousPatterns": [
    "rm -rf node_modules",
    "docker system prune"
  ]
}

customModels

Array of custom model configurations for local or remote OpenAI-compatible endpoints.

{
  "customModels": [
    {
      "id": "my-local-llama",
      "name": "Local Llama 3.2",
      "description": "Local model running in LM Studio",
      "modelId": "llama-3.2-3b",
      "baseUrl": "http://localhost:1234/v1",
      "contextLength": 128000,
      "category": "smart"
    }
  ]
}

Custom model API keys are stored securely in your system keychain, not in the config file.

Add custom models via CLI:

msh --add-model      # Interactive wizard
msh --list-custom    # List all custom models
msh --remove-model <id>  # Remove a custom model

Example Configurations

Strict Mode for Production

{
  "provider": "opencode-zen",
  "defaultModel": "deepseek-v4-flash-free",
  "safetyLevel": "strict",
  "dryRunByDefault": true,
  "theme": "nord"
}

Relaxed Mode for Development

{
  "provider": "opencode-zen",
  "defaultModel": "deepseek-v4-flash-free",
  "safetyLevel": "relaxed",
  "dryRunByDefault": false,
  "theme": "dracula"
}

OpenRouter with Premium Model

{
  "provider": "openrouter",
  "defaultModel": "anthropic/claude-sonnet-latest",
  "safetyLevel": "moderate",
  "dryRunByDefault": false,
  "theme": "catppuccin"
}

Editing the Config

Via CLI

Most settings can be changed via CLI options:

msh --provider openrouter
msh --model anthropic/claude-sonnet-latest
msh --theme tokyonight

Manually

Edit the file directly:

# Open in your editor
$EDITOR ~/.magic-shell/config.json

Via TUI

In TUI mode, press Ctrl+P and choose Show Config to view config and change settings.

Config Directory

The ~/.magic-shell/ directory also contains:

File	Description
config.json	Main configuration
history.json	Command history (if enabled)

Resetting Configuration

To reset to defaults, delete the config file:

rm ~/.magic-shell/config.json

A new default config will be created on next run.