Mi Code

VS Code-native agent runtime for private coding, document work, and controlled workspace automation.

Mi Code helps local or internal models do useful work inside VS Code by giving them a structured runtime for workspace evidence, file and document operations, command verification, bounded browser evidence, controlled autonomy, and clear stop conditions. It is designed for teams that care about privacy, traceability, and practical developer workflows more than chasing benchmark spectacle.

Mi Code is a self-guarded agent. It treats its own edits, tool choices, and final answers as claims that must be checked against current workspace evidence, git state, verification results, and explicit residual risk. Model confidence is not evidence.

Why Mi Code

Most coding agents assume a strong hosted model and focus mainly on code editing. Mi Code is built for the rougher but common reality of local, private, or internal models: tool calls may be imperfect, context can get crowded, and users need evidence before they trust the result.

Mi Code's stance is simple: do not rely on prompt cleverness alone. Let the runtime gather evidence, track state, verify changes, recover from weak model behavior, and stop cleanly when the boundary is unclear.

That means the agent should ask itself practical questions while it works: what did I inspect, what did I change, what was already changed by the user, what did verification cover, what failed, what can be repaired safely once, and what should be reported as a blocker or residual risk?

Mi Code is not a broad RPA or service automation platform. Its automation is workspace-centered and bounded: code, documents, local files, approved commands, browser evidence, and verification steps are handled inside one controlled VS Code-native runtime.

Key Features

• Private/local first: Uses Ollama by default and supports OpenAI-compatible, vLLM, and AIOps backends for internal deployments.
• Evidence-driven work: Shows what the agent inspected, changed, ran, verified, failed, retried, or left as residual risk.
• Self-guarded reliability: Checks agent claims against workspace/git evidence, separates user changes from agent changes, and treats failed verification as decision evidence instead of something to hide.
• Mode-aware runtime: Keeps General mode as a direct user/LLM conversation with optional tool execution, while Autonomous mode owns structured planning, judging, repair, and blocker decisions.
• Stable transcript UI: Orders thinking, tool calls, context events, final answers, retries, restored sessions, and prompt-preview readiness from request/runtime metadata instead of model prose or array order.
• Small-model practicality: Includes model profiles, tolerant parsing, readiness diagnostics, native tool calls where available, and text-based tool-call fallback when needed.
• Project understanding: Builds context from workspace files, VS Code language providers, diagnostics, project profiles, git evidence, repo maps, and SQL/schema signals before asking the model to guess.
• Controlled autonomy: Autonomous mode plans, executes, verifies, repairs, replans, or stops with evidence. It is bounded autonomy, not uncontrolled background execution.
• Code and documents together: Handles source code plus structured text-first DOCX workflows, read-only PDF evidence, and bounded read-only spreadsheet evidence in one VS Code-native surface.
• Controlled workspace automation: Connects file operations, document work, command evidence, browser snapshots/actions, and verification loops without becoming broad RPA, email, ERP, payment, or credentialed service automation.
• Safety boundaries: Uses approval policy, post-verification edit guardrails, repeated-failure limits, and typed blockers for sensitive or unclear work.

Who It Is For

Mi Code is useful when:

• You need coding assistance inside private, local, internal, or air-gapped environments.
• Your available models may not follow tool schemas perfectly.
• You want evidence, verification results, and residual risks before trusting agent work.
• You need code workflows and structured document workflows in the same VS Code extension.
• You want bounded workspace automation for files, commands, local/browser evidence, and verification without sending work into a broad hosted automation system.

🚀 Quick Start

1. Installation

Install from VS Code Marketplace:

1. Open VS Code Extensions (Ctrl+Shift+X)
2. Search for "Mi Code"
3. Click "Install"

Or install manually from a packaged VSIX file:

code --install-extension mi-code-*.vsix

2. Configuration

After installation, configure the following settings:

{
  "mi-code.provider": "ollama",
  "mi-code.modelProfile": "auto",
  "mi-code.model": "gemma4:e4b-coder",
  "mi-code.backendUrl": "http://127.0.0.1:11434",
  "mi-code.language": "ko",
  "mi-code.maxSteps": 50,
  "mi-code.temperature": 0.7,
  "mi-code.topP": 0.9
}

For OpenAI API usage, set the provider and API key. If model and backendUrl are not set globally, Mi Code uses the extension's current OpenAI default, gpt-5.5, and https://api.openai.com. vLLM and AIOps also have provider-specific backend defaults when no URL is set: http://127.0.0.1:8000 for vLLM and http://127.0.0.1:8080 for AIOps.

{
  "mi-code.provider": "openai",
  "mi-code.modelProfile": "generic",
  "mi-code.model": "gpt-5.5"
}

Use Mi Code: Set API Key to store the key in VS Code Secret Storage, or set MI_CODE_API_KEY in your environment. ChatGPT/Codex subscriptions do not include OpenAI API credits; API billing must be enabled separately.

For global configuration, use ~/.mi-code/config.json:

{
  "provider": "ollama",
  "model": "gemma4:e4b-coder",
  "backendUrl": "http://127.0.0.1:11434",
  "modelProfile": "auto",
  "language": "en"
}

3. Usage

1. Click the Mi Code icon in the left sidebar
2. Request tasks in the chat window!

First Coding Task

Start with a small, bounded request that can be inspected and verified in the current workspace:

Update the README setup note, run the relevant documentation check, and summarize changed files, verification, and any residual risk.

For a first task, Mi Code should inspect the relevant files before editing, preserve unrelated user changes, run or recommend the most relevant verification command, and report changed files plus verification results in the final answer. If a check fails, the agent should either repair a clear local issue once or stop with an honest blocker that names the failed command, completed source changes, and remaining risk.

Examples:

• "Add comments to src/runtime/tool-loop.ts"
• "Update dependencies in package.json"
• "Write a git commit message"
• "Refactor this function to use async/await"
• "Explain this code block"
• "Open a .docx file, switch to Document mode, and ask Mi Code to summarize or edit a section"
• "Create a .docx report from this outline and include a table"
• "Export an existing .md or .docx file to a text-based PDF"
• "Review this SQL migration for rollout risks without connecting to the database"
• "Inspect local schema/query evidence before suggesting SQL tuning candidates"
• "Inspect the docs and package metadata, update the public positioning copy, run the docs/package consistency checks, and summarize changed files, verification, and residual risk"

Working with DOCX Files

Mi Code can open .docx files in a read-only VS Code custom editor and use Document mode to inspect, create, modify, and validate files through DOCX-specific tools.

Typical workflow:

1. Open a .docx file in VS Code
2. Select Document mode in the Mi Code input
3. Mention the file with @path/to/file.docx or refer to a visible block/section
4. Ask for content changes, section edits, table updates, summaries, generated additions, or new documents from Markdown-style instructions

DOCX structure is exposed both as flat editable blocks and as a heading-derived outline, so the agent can plan around sections while still applying precise block/table edits. For the document runtime boundary and tool behavior, see Document Mode Design.

Document mode can also export existing .md, .markdown, or .docx files to .pdf with export_document_pdf. This is handled inside the extension without LibreOffice, Pandoc, browser automation, or external services. The built-in PDF export is text-based, so complex Word layout, images, headers, footers, pagination, custom fonts, and exact non-Latin font rendering may require a dedicated PDF renderer.

Existing PDFs can be opened in the read-only PDF Evidence Viewer and read through dedicated PDF evidence tools: get_pdf_metadata, get_pdf_text, get_pdf_page, and search_pdf_text. The viewer and tools report page/snippet/extraction-confidence evidence from the PDF text layer only. They do not edit PDFs, run OCR, reconstruct layout, extract images, or recover table structure.

Existing .xlsx and .xlsm files can be opened in the read-only Spreadsheet Evidence Viewer and inspected through read_spreadsheet. The viewer and tool report workbook metadata, sheet metadata, bounded grid previews, formula text/cached values, and risks such as hidden sheets, merged cells, external links, macros, and truncation. They do not edit spreadsheets, recalculate formulas, execute macros, fetch external links, export files, parse legacy .xls, or promise Excel/LibreOffice rendering fidelity.

The input settings menu includes Preview Prompt, which shows the assembled model-facing messages, active tools, run policy, phase, local model readiness, explicit project profile state, and context token state without sending the request. It can be opened even when the input is empty to inspect the system prompt.

Public Preview Limits

Mi Code is strongest in Git workspaces because current changed-file, ownership, diff, and continuity evidence can be gathered directly. Non-git and SVN workspaces can still use Mi Code for file inspection, edits, commands, project evidence, and document workflows. mi-code.vcsMode controls the workspace evidence expectation: auto checks for .git or .svn at the opened workspace root on runtime/profile checks, git keeps Git tools available, and none/svn hide Git-specific inspection tools while marking ownership, diff, and continuity evidence as weaker. If auto currently resolves to none, it means no root marker was detected yet; it is not a permanent instruction to avoid intentional setup commands such as initializing a repository, but routine Git inspection is not treated as approval-free workspace evidence until Git is detected at the opened root. /doctor also reports whether git or svn is available on PATH. SVN mode is an explicit fallback boundary, not SVN-specific integration yet.

The following areas are intentionally out of scope for the current public preview:

• durable workspace memory that silently persists project facts across sessions
• SVN-specific integration or full VCS workflow replacement
• spreadsheet editing, export, formula recalculation, macro execution, or high-fidelity rendering
• broad browser automation beyond the approved host-browser action surface, automatic login, CAPTCHA bypass, credential extraction, raw browser scripting, purchases, reservations, payments, or account mutation
• PDF editing, OCR, layout reconstruction, image extraction, or table recovery
• live database connections, query plans, or production database claims
• broad service/email automation or destructive external actions
• multimodal image/PDF attachment understanding beyond current text/evidence tools

Use /doctor, /status, and Preview Prompt when setup or model behavior is unclear.

📋 Configuration Options

Host browser connectivity exposes host_browser_snapshot, host_browser_navigate, and bounded host_browser_* element actions only after the user opens and connects a host Chrome/Edge CDP session from the input browser control. Browser actions stay snapshot/action based, reuse mi-code.approvalMode, and keep login/security steps user-handled by default. See Browser Evidence Boundaries for the full browser contract.

Command tools remain available as evidence and verification paths across direct, review, general execution, document, and autonomous worker routes. Run policy primarily controls whether edit tools are available; individual command execution is still governed by approval mode, command safety policy, repeated-failure blockers, and tool-specific guards.

🔧 Available Commands

Chat Commands

• /tasks - List current tasks
• /resume - Resume a paused task
• /status - Show agent runtime status
• /doctor - Run integrated setup and endpoint diagnostics
• /project - Show the saved explicit workspace project profile
• /project refresh - Inspect the workspace and save a fresh project profile
• /project clear - Remove the saved project profile
• /verification - Show workspace verification commands
• /verification set <command> - Replace workspace verification commands
• /verification add <command> - Add a workspace verification command
• /verification clear - Clear workspace verification commands
• /memory - Show compact session memory summary and the current memory policy
• /memory clear - Clear memory for the current conversation
• /memory delete <id> - Delete one memory item by id
• /memory view <view> - Show a scoped memory view (facts, decisions, artifacts, risks, todos, verification, or documents)

Settings Commands

• Mi Code: Open Settings - Open settings UI
• Mi Code: Set API Key - Set OpenAI-compatible API key
• Mi Code: Clear API Key - Remove stored API key

Utility Commands

• Mi Code: Open Chat - Open chat view
• Mi Code: Focus Chat View - Focus on chat
• Mi Code: New Conversation - Start fresh conversation
• Mi Code: Delete Conversation - Clear conversation history
• Mi Code: Open Test Browser - Request approval to launch an isolated host Chrome/Edge test browser session

Execution Modes

• General: coding-agent mode for normal explanation, edits, review, and verification.
• Autonomous: goal-driven mode that plans subtasks, executes them sequentially, verifies results, and stops with evidence when it cannot safely continue.
• Document: document-focused mode for structured text-first DOCX creation/editing, table updates, validation, PDF export, read-only PDF evidence, and bounded read-only spreadsheet evidence.

Document mode is designed for reports, outlines, tables, and controlled edits. It is not a pixel-perfect Word layout engine, OCR engine, PDF editor, image extractor, or table-recovery system.

Documentation

• Documentation index: docs/README.md
• Internal development guide: docs/development.md
• Product strategy, policy, and roadmap: docs/product-strategy.md
• Runtime flow and prompt rules: docs/run-modes-and-prompts.md
• Extension architecture: docs/architecture.md
• Autonomous mode design: docs/autonomous-agent-design.md
• Work control foundation: docs/work-control-foundation.md
• Local model configuration notes: docs/local-model-configs.md
• Runtime observability contract: docs/runtime-observability.md
• Long-term roadmap: docs/long-term-roadmap.md
• Open and deferred items: docs/open-items.md
• Score blocker regression matrix: docs/score-blocker-regressions.md
• Current release notes: CHANGELOG.md

Completed version plans are consolidated into the grouped release notes, durable roadmap lessons, and open-items backlog instead of being kept as active planning documents.

🔒 Security & Data Handling

• Local-First by Default: The ollama provider sends requests only to your local Ollama server
• Remote API Warning: Using openai, vllm, aiops, or a remote backendUrl may send prompts, code context, and tool results to external APIs
• API Key Management: Use Mi Code: Set API Key command or MI_CODE_API_KEY environment variable for OpenAI-compatible APIs
• Approval Modes: Sensitive operations (file deletion, terminal commands, Git modifications) require user approval in prompt mode
• Approval Visibility: auto is the default for convenience and is shown with warning-colored approval indicators in the chat UI. Switch to prompt when high-impact tools should require explicit confirmation
• Privacy: No telemetry or data collection by default

🆘 Support & Resources

• Issues & Feature Requests: GitHub Issues
• Changelog: CHANGELOG.md
• License: MIT

When reporting a problem, include:

• Mi Code version
• VS Code version
• Operating system
• Provider setting (ollama, openai, vllm, or aiops)
• Model and model profile settings
• Execution mode (general, autonomous, or document)
• Whether native tool calls are rejected by the backend
• Relevant error messages from the Mi Code output channel
• Whether /doctor, /status, and /tasks show anything unusual

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Commit your changes (git commit -m 'Add some feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Please keep changes focused, run the relevant checks, and describe the verification performed in your pull request.

📝 Changelog

See CHANGELOG.md for recent changes.

📄 License

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

🙏 Acknowledgments

Mi Code was built with privacy in mind for developers who value local-first AI.

VS Code Version Requirement: 1.85.0 or higher