KoMind

An AI coding agent that lives in your VS Code activity bar — chat, read and edit files, run commands behind an approval gate, and bring your own model.

KoMind embeds a coding agent in VS Code. It talks to any Anthropic- or OpenAI-compatible endpoint (OpenAI, Azure AI Foundry, OpenRouter, Groq, local Ollama/LM Studio, and more), reads and edits your files with visual diffs, runs terminal commands only after you approve them, and keeps every chat so you can reload it later.

Features

• 🤖 Agent in the sidebar — chat, and let it read files, search code, apply multi-file edits, and run commands.
• 🔌 Bring any model — point it at any Anthropic- or OpenAI-compatible API; mix providers and switch models mid-chat.
• 🛡️ Approval gate — terminal commands and external (MCP) tools require explicit approval; keys live in VS Code SecretStorage.
• ✍️ Visual diffs — edits are applied as reviewable changes you track in Source Control.
• ✅ Loop engineering (unreleased, local source) — act → host verify → bounded repair → reverify, with persisted check evidence separate from agent completion. See Verification after edits.
• 💾 Persistent sessions — every chat is saved and reloadable from a dropdown; import chats from other AI providers.
• 🎙️ Voice input — dictate prompts; the transcript lands in the box for review before sending.
• 🧩 Skills & plugins — drop reusable instruction packages and slash commands into your workspace.
• 🛠️ MCP tools — connect Model Context Protocol servers (GitHub, databases, browsers, …) with no code changes.

Quick start

1. Install KoMind from the Marketplace, then click the KoMind icon in the Activity Bar to open Agent Chat.
2. Set your API key — open Settings (gear icon), paste your key into API key, and click Save (or run KoMind: Set API Key). It takes effect immediately and is stored in SecretStorage, never on disk in plaintext.
3. Pick your provider — the default koMind.baseUrl works out of the box; to use OpenAI, Azure AI Foundry, or a local model, see Any provider below.
4. Start chatting. Edits apply as reviewable diffs; terminal commands wait for your approval.

Settings

Any provider: base URL + API type

KoMind works with whatever provider the API base URL in Settings points at. API type (default Auto) picks the request format from the URL:

If Auto guesses wrong, choose the type by hand. For Azure AI Foundry, paste the project URL and the resource key (Azure portal → Foundry resource → Keys and Endpoint) in Settings, then add your deployment name (e.g. gpt-6-astra) under Extra models.

Several providers side by side

To use models from more than one provider at once, list extra endpoints in settings.json (kind: openai-responses, openai-chat or anthropic). A model goes to the endpoint that lists it, and any other model goes to koMind.baseUrl (the default endpoint):

"koMind.endpoints": [
  {
    "name": "azure",
    "kind": "openai-responses",
    "baseUrl": "https://<resource>.services.ai.azure.com/openai/v1",
    "models": ["<deployment-name>"]
  }
]

Then run KoMind: Set Endpoint API Key, pick azure, and paste the resource key (Azure portal → your Foundry resource → Keys and Endpoint). The deployment then appears in the model picker, and you can switch between it and your Claude models mid-chat.

• kind: "openai-responses" uses the OpenAI Responses API (OpenAI, Azure OpenAI, Azure AI Foundry /openai/v1). Reasoning summaries show up as thinking. Effort extra/max is sent as high.
• kind: "anthropic" uses the Anthropic Messages API, e.g. Claude on Foundry at https://<resource>.services.ai.azure.com/anthropic.
• Use the /openai/v1 inference URL, not the project URL (/api/projects/<name>).
• Not supported: Azure AD / Entra ID sign-in (use the resource key).

Voice input

Click the mic button next to Send, speak, then click it again (it shows a red timer while recording). The transcript is inserted into the message box for review — it is never sent automatically. Esc or ✕ discards the recording; recordings stop on their own after 2 minutes.

VS Code webviews cannot access the microphone, so the extension host records audio itself: on Windows through built-in Windows APIs (no installs), on macOS/Linux through ffmpeg (must be on PATH). The audio is sent to an OpenAI-style audio/transcriptions endpoint.

Azure AI Foundry setup

1. In your Foundry project, deploy a speech-to-text model such as whisper or gpt-4o-transcribe.
2. Open KoMind Settings → Voice input and set the transcription URL: https://<resource>.openai.azure.com/openai/deployments/<deployment>/audio/transcriptions?api-version=2025-03-01-preview (a *.cognitiveservices.azure.com endpoint works too). Leave Model empty.
3. Paste the resource's API key into Voice API key and click Save (or run KoMind: Set Voice Input API Key). It is kept in SecretStorage.

Azure hosts are authenticated with the api-key header; other hosts (OpenAI, Groq, local Whisper servers) get Authorization: Bearer <key> — set Model (e.g. whisper-1) for those.

MCP servers (external tools)

KoMind can connect to Model Context Protocol servers to add third-party tools (GitHub, databases, docs, browsers, …) without any code changes. Configure them under koMind.mcpServers, keyed by a short server name:

"koMind.mcpServers": {
  "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
  "docs":   { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer …" } }
}

• stdio servers — set command plus optional args, env, cwd.
• HTTP servers — set url plus optional headers (Streamable HTTP transport).
• Set "enabled": false to keep a server configured but disconnected.

Connected servers' tools appear to the agent namespaced as mcp__<server>__<tool> and render as server · tool in the chat. Every MCP tool call requires explicit approval — external servers are untrusted and the always-allow grants do not apply to them.

Security: MCP servers are external processes with access to your machine and any credentials you pass them. Only add servers you trust.

Skills

Skills are reusable instruction packages the agent loads on demand. A skill is a directory containing a SKILL.md file:

.komind/skills/
  pdf-forms/
    SKILL.md

SKILL.md has optional YAML frontmatter (name, description) followed by the instruction body:

---
name: pdf-forms
description: Fill and extract data from PDF forms
---

# Filling PDF forms

1. Use `pdftk` to inspect fields: `pdftk form.pdf dump_data_fields`
2. ...

KoMind discovers skills from two locations (workspace takes precedence on name collisions):

• <workspace>/.komind/skills/ — project-specific skills, checked into the repo
• <globalStorage>/skills/ — personal skills available in every workspace

At startup the agent's system prompt gets a compact index of skill names and descriptions. When a request matches, the model calls the load_skill tool to pull in the full body before proceeding — so many skills can exist without bloating the context.

Skills are untrusted content: their instructions are treated as data. Review a workspace's skills before relying on them.

Plugins & slash commands

Plugins bundle skills, MCP servers, slash commands, and a system-prompt fragment behind a single manifest. A plugin is a directory containing komind-plugin.json:

.komind/plugins/
  code-quality/
    komind-plugin.json
    skills/
      style-guide/
        SKILL.md

{
  "name": "code-quality",
  "description": "Code review helpers",
  "systemPrompt": "Prefer small, focused diffs.",
  "commands": [
    { "name": "review", "description": "Review a diff", "template": "Review the following and flag issues:\n\n{{args}}" }
  ],
  "mcpServers": {
    "linter": { "command": "npx", "args": ["-y", "@example/mcp-linter"] }
  },
  "skills": ["skills"]
}

All sections are optional. Plugins are discovered from <workspace>/.komind/plugins/ and <globalStorage>/plugins/. Their contributions are wired in automatically:

• Skills — loaded into the skill index (see above).
• MCP servers — connected on startup, namespaced by plugin (<plugin>-<server>).
• System prompt — appended to every session's system prompt.
• Slash commands — typing /name args in the chat expands to the command's prompt template. {{args}} is replaced with what you type after the command; without a placeholder, your text is appended. The composer shows an autocomplete menu as you type /. Duplicate command names across plugins are namespaced (<plugin>-<name>).

Plugins are untrusted content, just like skills and MCP servers. Review a plugin's manifest before enabling it.

Tool permission model

• Edits (apply_edit): accepted edits are always saved immediately, independent of VS Code's files.autoSave setting, so no Save/Don't Save prompt is needed. autoApproveEdits only controls whether approval is required before applying an edit and defaults to true. Review changes with Git/Source Control. Non-unique or missing oldString matches are rejected with an error.
• Terminal (run_terminal): requires explicit user approval in the chat card (Approve/Reject buttons). Unanswered requests auto-reject after 60 seconds.

Verification after edits

Status: this feature is implemented in local source changes only. It has not yet been installed or released, and runtime UI verification in VS Code is still pending.

Loop engineering names the feedback loop: act → host verify → bounded repair → reverify. It does not require an upfront planning phase or a mandatory state-machine workflow. The host, not the model's completion claim, owns the checks and evidence.

The host requires verification after code edits, including worker (sub-agent) edits. Executed agent/worker shell commands and external-tool invocations are conservatively treated as potentially mutating, even if they look read-only or fail. Read-only access, including reading protected files, remains exempt when no earlier unverified changes are pending.

Plain .md/.rst edits are exempt only without custom protected globs and outside built-in protected paths: test, tests, __tests__, fixtures, spec, specs, and common test/config filenames or directories (for example config/, settings/, or docs/runner.config.md). Gate-created trackers classify mutations before writing, including newly created documents. Any configured custom protectedGlobs conservatively makes all .md/.rst edits require checks; only actual changed protected inputs trigger the additional human review, not this broad classification alone. A docs-only turn using shell/external tools is not exempt.

Agent completion is not verification. The completion summary and host verification card are separate. The verification card shows Verified — configured checks passed, Not verified — checks failed, Not verified — checks incomplete, or Verification not required (and a running state during checks). Status and check evidence are persisted across reloads. The same bounded diagnostics (command, working directory, status, exit code and output) support repair feedback and remain available on continue/reload. Model claims, worker completion, and ad-hoc terminal successes cannot set the host's verified status.

Configure required checks

Set these in VS Code settings.json before starting the turn:

• koMind.verification.commands: up to 20 entries with required name and command, plus optional cwd, successText, and testReport. Every check must exit with code zero and satisfy any configured evidence requirements. Commands run in order, stopping at the first failed or incomplete check.
  • cwd is workspace-relative and defaults to the workspace root.
  • successText requires a literal substring, not a regex, in the last 32,000 captured output characters in addition to exit code zero. Persisted evidence contains the last 8,000 characters. Earlier markers may be truncated; this option is not evidence that tests ran.
  • testReport is a workspace-relative path to a Vitest/Jest JSON report, independent of cwd. Recommended for test commands: the host requires success: true, a fresh startTime within the current command run, a nonzero total test count, all tests passed, and no failed, pending/skipped, or todo tests. Missing, malformed, stale, empty, or unsuccessful reports fail the check.
• koMind.verification.maxRepairAttempts: defaults to 3 (0–10). Failed checks, including nonzero exit codes or rejected test evidence, feed back into bounded AI repair attempts followed by rechecks. Repair also needs remaining model rounds; 0 disables repair, not checks. Required host checks run outside the model round budget, after the last edit and before the tools-disabled wrap-up. Exhaustion stops AI repair, never bypasses checks or their approval/mode restrictions.
• koMind.verification.timeoutMs: defaults to 120000 per command, excluding approval time. Cancellation during checks waits for process-tree cleanup and leaves work unverified. Cancelling the later tools-disabled wrap-up stops the task but preserves completed host-check status and evidence for the unchanged revision, including failure diagnostics.
• koMind.verification.protectedGlobs: optional additional workspace-relative globs (up to 20) for custom test runners, scripts, or fixtures. Common test/config inputs are guarded by default. Custom globs also disable the plain-doc edit exemption as described above. Snapshot guards cover common text sources and are bounded to 5,000 files; unreadable/oversized inputs block verification rather than silently passing.

Terminal completion cleans up remaining owned background processes before checks start. Avoid daemon/watch commands: Unix process groups and Windows parent-PID discovery are lifecycle controls, not a sandbox. Deliberately detached processes, and Windows descendants whose intermediate parent exits before discovery, can escape these controls; a Verified card describes captured checks, not permanent containment or future workspace immutability.

The strict testReport policy still rejects all skipped/todo tests, including legitimate platform-specific skips. Non-applicable tests exist on both sides: Windows skips KoMind's Unix process-group tests; Unix skips its Windows process-tree test. Switching OS alone does not resolve this. Full green strict verification remains blocked pending an explicit, human-reviewed cross-platform policy. Do not weaken commands, remove report validation, remove/skip tests, or fabricate evidence to obtain a green badge. Commands without testReport attest only to their exit status and optional successText, not to test coverage; that distinction is not a workaround for the strict policy.

The command list is pinned at turn start, so editing settings mid-turn cannot weaken the active checks. Existing terminal approvals, auto-approval settings, and mode restrictions still apply. Changes to tests or check inputs (such as package scripts, lockfiles, and check configuration) require a separate, explicit human review of the diff before verification. This review is non-sticky: terminal auto-approval and Always Allow cannot approve it. Confirm that required tests have not been removed, skipped, or weakened. Further input changes during review invalidate that approval; detected source/check-input changes during verification make its results stale.

No configured commands, invalid configuration, denied approval/review, unavailable terminal access, timeout, cancellation before checks finish, or stale results leave changes Not verified, not passed. Incomplete checks do not trigger automatic repair retries. Pending unverified changes carry into later turns; resuming without the original input baseline requires human review. For disposable-workspace scenarios and unverified runtime cases, see the manual smoke checklist.

Example: checks for the KoMind repository

With the KoMind repository open as the workspace and its development dependencies available, merge these settings into settings.json:

{
  "koMind.verification.protectedGlobs": ["esbuild.js"],
  "koMind.verification.commands": [
    {
      "name": "Typecheck",
      "command": "npm run check"
    },
    {
      "name": "Unit tests",
      "command": "npm run test:unit -- --reporter=json --outputFile=.komind/verification-results.json",
      "testReport": ".komind/verification-results.json"
    },
    {
      "name": "Compile",
      "command": "npm run compile"
    }
  ],
  "koMind.verification.maxRepairAttempts": 3,
  "koMind.verification.timeoutMs": 120000
}

The .komind directory is usually already present. If needed, create it from the repository root before the turn so the test reporter can write its output:

node -e "require('node:fs').mkdirSync('.komind', { recursive: true })"

npm run check uses the new tsconfig.check.json, which scopes typechecking to source and supported tests, leaving out old scratch copies in test/unit. The legacy broad npx tsc --noEmit still includes those copies and has unrelated errors. npm run test:unit runs Vitest once (not in watch mode); the example requests a fresh JSON report. npm run compile builds the production bundles locally — it does not install or release the extension or verify the running UI.

The repository's protectedGlobs explicitly guards esbuild.js, which implements the production build check. This also makes documentation edits require checks in this repository. The current build writes generated integration bundles under test/integration/; if those outputs change during host verification, the protected-input snapshot deliberately rejects the results as stale. Keep that limitation visible rather than exempting test files or weakening the checks.

Trust boundary: use trusted check definitions and review the scripts, test selection, and configuration they depend on. A zero exit code alone does not prove tests ran; use testReport for machine-checked test evidence. Even a valid report only establishes what the trusted suite reports, not coverage or correctness. This gate is not a sandbox or proof of bug-free software. Configure local, non-watch checks, never deployments or live-database writes.

npm install

npm run check             # scoped typecheck (tsconfig.check.json)
npm run test:unit         # vitest (including host verification)
npm run test:integration  # @vscode/test-electron (activation, commands)

src/
  host/        extension entry, provider, agent, tools, approvals, store
  webview/     React chat UI
  shared/      typed message protocol
test/
  unit/        vitest suites
  integration/ vscode-test-electron suite
esbuild.js     bundler (host + webview)

About KOMOCS

KoMind is built and maintained by KOMOCS (King of Modern Code Solutions) — a technology partner offering AI integration, process automation, software engineering, cloud & infrastructure, data & intelligence, and technology advisory. Technology solutions built to the shape of your problem.

📍 Jaffna, Sri Lanka  ·  ✉️ hello@komocs.com  ·  📞 +94 76 972 2216

🌐 komocs.com  ·  LinkedIn  ·  Facebook  ·  Instagram