Mi Code

Personal, local-first VS Code coding/work agent for small and local models.

Mi Code lets a primary model inspect workspace state, edit files, run commands, work with documents and spreadsheets, use connected browser capabilities, and load packaged domain Skills when a task benefits from service-specific workflow guidance. The runtime supplies context, tools, receipts, structured failures, and continuity while leaving semantic decisions with the model.

user request
-> bounded context + exposed capabilities
-> primary model chooses text or ToolCall
-> runtime executes the exact call
-> receipts/results return to the model

Product model

Mi Code is designed for one local user on their own machine. The user chooses/trusts the workspace and chooses the model/provider/backend.

The runtime is not a hidden planner, completion judge, semantic router, or second assistant. Normal user-directed local work is the primary requirement; security/safety machinery is kept only where a small concrete effect/resource boundary provides real product value.

Mi Code is a local-first tool for a trusted local workspace. The selected provider/model and the capabilities available in the current VS Code session determine which tasks can run.

Weak-model assistance

Mi Code is deliberately optimized for models that may have limited context or imperfect tool-call reliability.

It helps through:

• a clear “act now when tool-backed work is needed” model instruction;
• bounded current workspace/editor context;
• model-facing tool schemas;
• a compact built-in Skill catalog with model-selected progressive loading;
• provider-native tool-call reconstruction and normalization;
• exact execution receipts and failures;
• bounded post-receipt primary-model recall;
• neutral recovery from malformed, empty, thinking-only, or truncated turns.

The runtime does not decide that ordinary model text is incomplete and does not select a semantic next action on the model's behalf.

Core principles

• Model-led work — the primary model chooses whether to answer or call an exposed tool and which tool to call.
• Useful local operation first — trusted local user/workspace/provider assumptions should not be wrapped in speculative hostile-environment architecture.
• Exact execution — the runtime executes model-emitted calls through real capability/run-policy, exact target/current-state, cancellation, owner/executor, and receipt boundaries.
• Observed-effect truth — assistant prose is not proof of a read, write, command, verification, commit, browser action, or document effect; receipts/state deltas are.
• Append-only answers — every non-empty primary-model generation remains visible.
• Separate sidecars — runtime report and task status never rewrite the assistant answer.
• Deletion over defensive state — generations, leases, fences, deny lists, arbitrary ceilings, and proof protocols require concrete supported-product value or should be removed.

Features

• Ollama by default; OpenAI, vLLM, and OpenAI-compatible enterprise endpoints are configurable.
• Workspace reads/search/edits and diagnostics.
• Terminal command execution through the delegated run-policy/capability boundary with exact current execution checks.
• Document, PDF, and spreadsheet reading/editing/export surfaces.
• Connected host-browser snapshot and action tools.
• Model-selected built-in Skills provide packaged domain guidance without adding a second execution authority. Current packaged domains include Jira, Confluence, Mattermost, local Git, GitHub, and GitLab.
• Image attachments for multimodal-capable providers.
• General, Autonomous, and Document execution surfaces sharing the same model-led action boundary.
• Append-only conversation/session continuity and factual runtime reports.
• /doctor, /status, Profile Check, and prompt/tool diagnostics for model/provider troubleshooting.

Quick start

1. Install a VSIX or available public-preview build:

   • CLI: code --install-extension mi-code-*.vsix
   • VS Code: open the Extensions view, choose Install from VSIX, and select the package.

2. Configure a provider/model, for example:

   {
     "mi-code.provider": "ollama",
     "mi-code.modelProfile": "auto",
     "mi-code.model": "qwen3.5:9b",
     "mi-code.backendUrl": "http://127.0.0.1:11434"
   }
   

3. Use Mi Code: Set API Key if the selected provider needs a credential.

4. Open the Mi Code sidebar. Open a workspace when you want workspace files, editor/code tools, terminal/Git, verification, or workspace-scoped document/spreadsheet work; general chat and independently available Skills, Host Browser, Services, and direct image attachments do not require a synthetic workspace.

5. Run /doctor, then /check simple when workspace diagnostics are relevant, then try one narrow real task.

Configured verification commands are candidates/context for the model; their presence does not authorize automatic execution.

What you can ask Mi Code to do

Mi Code is meant to be used with ordinary task requests, not internal tool names. For example:

• Understand a project — “Explain how authentication flows through this project,” “Find where this error is produced and explain the call path,” or “Compare these two implementations and tell me the trade-offs.” Mi Code can inspect and search workspace files when the request needs it.
• Change code and verify it — “Fix this bug and run the relevant tests,” “Refactor this function without changing behavior,” or “Update these files and tell me exactly what changed.” File edits and terminal commands depend on the delegated capabilities and exact current execution boundaries available in the session; normal delegated agent ToolCalls do not require a second generic approval prompt.
• Review current changes — “Review the current project changes from a user-impact perspective” or “Check this implementation for regressions and missing tests.” Git can provide optional change evidence; Git is not required for ordinary project work.
• Use built-in domain Skills — Ask naturally, for example “Check this Jira issue and add a comment,” “Review this GitHub pull request,” or “Check why this GitLab pipeline failed.” The primary model decides whether a packaged Skill is relevant, loads its guidance, and then chooses from the existing exposed tools; loading a Skill does not grant new capability.
• Work with documents and spreadsheets — “Summarize this DOCX,” “Update this document,” or “Inspect this spreadsheet and export the result.” Supported operations depend on the file type and the active Document/Spreadsheet surface; PDF viewing and export are available only where the relevant tool is supported.
• Use a browser — “Open this page and summarize it” or “Fill this form.” These requests require a ready Host Browser session; Mi Code does not claim browser access when that capability is unavailable.
• Inspect images — Attach an image or mention a supported workspace image and ask “What is shown here?” Image understanding requires a selected model/provider profile with image input support.

Give a request explicit context

Opening or focusing a file alone does not attach it to the request. Use an editor selection, @ mention, or request-target when you want to provide explicit file context. Type @ in the composer to choose a workspace file or folder, then include a request such as “Review @src/auth.ts for this error.” The suggestion list shows the targets available in the current workspace.

Choose a work surface

• General is for questions, project understanding, reviews, focused edits, and normal coding work.
• Autonomous lets Mi Code continue through bounded worker turns for a larger request; the model still chooses each semantic action.
• Document exposes document/spreadsheet-oriented tools, including DOCX editing where supported.

Availability can vary with the selected provider, model profile, open workspace, file format, delegated run-policy/capability, and Host Browser/Service readiness. Without a workspace, workspace-scoped capabilities are unavailable while general chat and independently configured non-workspace capabilities remain usable. If a capability is unavailable, /doctor and /status help show the current configuration and runtime state.

Runtime surfaces

• General — chat, explanation, review, narrow edits, and ordinary repository work.
• Autonomous — bounded continued worker turns; the primary model still chooses semantic actions.
• Document — document/spreadsheet-oriented tool exposure with the same exact-call model boundary.

Execution surfaces change capabilities/context, not who decides what to do.

Terminal and Git

Intentional terminal and Git work uses the generic command path.

exact selected command
-> delegated run-policy/capability + current technical checks
-> shell/OS
-> actual stdout/stderr/exit/state observations

Structural parsing may improve receipts, diagnostics, or risk presentation, but it does not decide whether an exact selected command may execute.

Normal delegated terminal/Git ToolCalls do not enter a generic human-approval lifecycle.

Data handling

Local-first does not mean every byte stays local. A remote provider or embedding endpoint explicitly configured by the user may receive the context required by the enabled feature.

API keys belong in VS Code Secret Storage, not ordinary conversation/log data. MI_CODE_API_KEY is reserved for automated tests and development fixtures.

Mi Code-owned workspace data is stored under ~/.mi-code/workspaces/<workspace-key>/. No-workspace conversations and feature-owned no-workspace state use extension-owned storage rather than pretending that storage is a workspace. Mi Code: Reset Workspace Data targets Mi Code-owned data for the current workspace and must not delete actual workspace source files or unrelated workspace roots. Its direct destructive UI confirmation is an accidental-click safeguard, separate from agent ToolCall execution authority.

API keys should use Mi Code: Set API Key. Use Mi Code: Clear API Key from the Command Palette when switching to an anonymous provider. Automated tests and development fixtures may use MI_CODE_API_KEY; do not include credentials, proprietary source, private documents, or browser/session data in prompts or public support reports.

Support

For setup or reproducible behavior, run /doctor, /status, and /check simple, then retry with one narrow task. Include the Mi Code version, VS Code version, OS, install source, provider/model/profile shape without credentials, the smallest reproduction prompt, and the visible result or error. The packaged Security Policy (SECURITY.md) explains the supported security boundary. This distribution does not publish a public security-reporting endpoint; use the private channel supplied with your installation when one is provided.

Validation

Use the smallest useful check for the change. Historical phase/batch migration documents are not part of the development process.

Useful commands include:

npm run build
npm run check-types
npm run lint
npm run check:docs
npm run check:i18n

Live model behavior belongs to dogfood/measurement rather than deterministic CI truth.

Documentation

The extension package includes SUPPORT.md, SECURITY.md, and CONTRIBUTING.md for users and maintainers who need the longer package-local guidance. Internal architecture contracts stay with the source repository and are not required for ordinary use.

CHANGELOG.md owns user-facing change history. Git/GitHub own implementation history; completed plans and migration archives are not kept as current product documentation.

Contributing and support

The package includes contributor, support, and security guidance alongside the README.

Mi Code is licensed under the MIT License.