README.md

Config File

Located at ~/.mandocode/config.json

{
  "ollamaEndpoint": "http://localhost:11434",
  "modelName": "minimax-m2.7:cloud",
  "modelPath": null,
  "temperature": 0.7,
  "maxTokens": 4096,
  "ignoreDirectories": [],
  "enableDiffApprovals": true,
  "enableTaskPlanning": true,
  "enableTokenTracking": true,
  "enableThemeCustomization": true,
  "enableFallbackFunctionParsing": true,
  "functionDeduplicationWindowSeconds": 5,
  "maxRetryAttempts": 2,
  "music": {
    "volume": 0.5,
    "genre": "lofi",
    "autoPlay": false
  }
}

All Options

CLI Config Commands

mandocode config show              # Display current configuration
mandocode config init              # Create default configuration file
mandocode config set <key> <value> # Set a configuration value
mandocode config path              # Show configuration file location
mandocode config --help            # Show help

Environment Variables

When the AI writes or deletes a file, MandoCode intercepts the operation and shows a color-coded diff before applying changes.

What You See

• Red lines — content being removed
• Light blue lines — content being added
• Dim lines — unchanged context (3 lines around each change)
• Long unchanged sections are collapsed with a summary

Approval Options

For new files, "don't ask again" sets a global bypass — all future writes and deletes are auto-approved for the session. For existing files, the bypass is per-file.

Even when auto-approved, diffs are still rendered so you can follow along.

Delete Approvals

File deletions show all existing content as red removals with a deletion warning. The same approval options apply.

Toggle

mandocode config set diffApprovals false

Type @ anywhere in your input (after a space or at position 0) to trigger file autocomplete. A dropdown appears showing your project files, filtered as you type.

How It Works

1. Type your prompt and hit @ — a file dropdown appears
2. Type a partial name to filter (e.g., Conf) — matches narrow down
3. Use arrow keys to navigate, Tab or Enter to select
4. The selected path is inserted (e.g., @src/MandoCode/Models/MandoCodeConfig.cs)
5. Continue typing and press Enter to submit
6. MandoCode reads the referenced file(s) and injects the content as context for the AI

Examples

explain @src/MandoCode/Services/AIService.cs to me
what does the ProcessFileReferences method do in @src/MandoCode/Components/App.razor
refactor @src/MandoCode/Models/LoadingMessages.cs to use fewer spinners

Multiple @ references in one prompt are supported. Files over 10,000 characters are automatically truncated.

Controls

MandoCode automatically detects complex requests and offers to break them into a step-by-step plan before execution.

Triggers

The planner activates for requests like:

• Create a REST API service with authentication and rate limiting for the user module (12+ words with imperative verb and scope indicator)
• Build an application that handles user registration and sends email confirmations
• Numbered lists with 3+ items
• Requests over 400 characters

Simple questions, short prompts, and single-action operations (delete, remove, read, show, list, find, search, rename) bypass planning automatically.

Workflow

1. Detection — heuristics identify complex requests
2. Plan generation — AI creates numbered steps
3. User approval — review the plan table, then choose: execute, skip planning, or cancel
4. Step-by-step execution — each step runs with progress tracking
5. Error handling — skip failed steps or cancel the entire plan

See Task Planner Documentation for full technical details.

The /learn command helps new users understand local LLMs and get set up.

Educational Content

1. What are Open-Weight LLMs? — Free, private, offline models vs. cloud AI
2. Model Sizes & Hardware — Parameters, quantization, VRAM requirements
3. Cloud vs Local Models — Ollama cloud models (no GPU) vs local models
4. Recommended Models — Table of cloud and local options
5. Getting Started — Step-by-step setup instructions

AI Educator Chat Mode

When Ollama is running, /learn offers an interactive chat mode where the AI explains LLM concepts using beginner-friendly language. Type /clear to return to normal mode.

MandoCode speaks the Model Context Protocol as a client, which means you can plug in any published MCP server — filesystem, database, GitHub, Linear, Slack, whatever — and its tools show up to the model alongside MandoCode's built-in plugins.

Adding a server

Two ways:

• /mcp add inside MandoCode — an interactive wizard that prompts through name, transport, URL/command, and optional headers/env vars, previews the JSON, and saves + reloads automatically.
• Hand-edit ~/.mandocode/config.json — useful when copy-pasting a mcpServers block from a server's README. Run /mcp-reload after saving.

Config shape

The mcpServers block mirrors Claude Desktop's schema, so you can copy-paste any server's README installation snippet directly into ~/.mandocode/config.json:

{
  "enableMcp": true,
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allow"]
    },
    "solana": {
      "url": "https://mcp.solana.com/mcp",
      "transport": "http"
    },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ghp_your_token_here" },
      "autoApprove": ["list_issues", "get_pr"]
    }
  }
}

Transports

• stdio — for local servers. Populate command + args + optional env. Works with any server published as an npm/pip/go binary.
• HTTP / SSE — for remote servers. Populate url; the client auto-detects Streamable HTTP or SSE. Custom headers go in headers — most commonly Authorization: Bearer … for servers that accept static tokens.

Does MandoCode need Node?

No. MandoCode itself is pure .NET. But individual servers may need whatever runtime their command points at — Node for npx, Python for uvx, or nothing extra for standalone binaries. Same situation as Claude Desktop, Cursor, and VS Code.

OAuth-only servers

Native OAuth is not in this release. For servers that require an OAuth flow (some hosted connectors like Google Drive), wrap them in stdio via the community mcp-remote proxy, which handles the browser dance itself:

"gdrive": {
  "command": "npx",
  "args": ["mcp-remote", "https://example.com/mcp"]
}

Approvals

MandoCode cannot tell a read-only MCP tool from a destructive one by inspecting arguments, so the first call of each (server, tool) pair prompts you with Approve / Approve for session / Deny. Pre-trusted tools can be listed under autoApprove in a server's config entry to skip the prompt entirely.

Slash commands

• /mcp — shows each configured server with its transport, connection status, and live tool count
• /mcp add — interactive wizard for adding a new server without hand-editing JSON
• /mcp remove <name> — remove a server from config (with confirm)
• /mcp tools <server> — list every tool exposed by connected servers with descriptions (server arg optional — omit to list all)
• /mcp-reload — tears down every MCP client, restarts them, and re-registers their tools on the kernel (useful when you edit the config mid-session)

Toggle

mandocode --config set mcp false   # disable all MCP integration

Individual servers can be muted without deleting them — set "disabled": true on any entry in mcpServers.

FileSystemPlugin

The AI has sandboxed access to your project directory through these functions:

Security: All operations are sandboxed to the project root. Path traversal is blocked with a separator-boundary check.

Ignored directories: .git, node_modules, bin, obj, .vs, .vscode, packages, dist, build, __pycache__, .idea — plus any custom directories from your config.

WebSearchPlugin

The AI can search the web and fetch page content — no API keys required.

Web search uses DuckDuckGo's HTML endpoint. Fetched pages are cleaned of scripts, nav, and non-content elements via HtmlAgilityPack.

Retry Policy

Transient errors (HTTP failures, timeouts, socket errors) are retried with exponential backoff:

Attempt 1 -> fail -> wait 500ms
Attempt 2 -> fail -> wait 1000ms
Attempt 3 -> fail -> throw

Function Deduplication

Fallback Function Parsing

Some local models output function calls as JSON text instead of proper tool calls. MandoCode detects and parses:

• Standard: {"name": "func", "parameters": {...}}
• OpenAI-style: {"function_call": {"name": "func", "arguments": {...}}}
• Tool calls: {"tool_calls": [{"function": {"name": "func", "arguments": {...}}}]}

Markdown Rendering

AI responses are rendered as rich terminal output:

Syntax highlighting supports C#, Python, JavaScript/TypeScript, and Bash with language-specific keyword coloring.

Token Tracking

• Per-response: [~1.2k in, 847 out] after each AI response
• Session total: Total [4.2k tokens] above the prompt
• File estimates: @file attachments show estimated token cost (chars/4)

Event-Based Completion Tracking

Function executions use semaphore-based signaling, ensuring each task plan step fully completes before the next begins.