Compile-time SDK for building Minga editor extensions.
This package provides the types, behaviours, macros, and API stubs that extension authors need to compile their code. At runtime, the real Minga modules in the editor's BEAM VM take over.
The full extension guide lives in the Minga repository: Extension API covers every callback and API with examples, and Extensibility explains the model behind it. Module documentation for this package is on HexDocs.
Installation
Add minga_sdk to your extension's dependencies exactly like this:
def deps do
[
{:minga_sdk, "~> 0.1", only: [:dev, :test], runtime: false}
]
endBoth options matter. The SDK only defines compile-time stubs of modules the editor already has, so it must never be loaded next to the real ones. only: [:dev, :test] keeps it out of your extension when Minga installs it, and runtime: false keeps it out of your release. As a second safeguard, the SDK compiles no modules at all when it is built inside a running Minga editor.
Compatibility
| minga_sdk | Minga |
|---|---|
| 0.1.x | main from jsmestad/minga#3756 (model routes with setup rows and plan usage) onward; the first rolling build after that merge and later |
The SDK is versioned separately from Minga. A minor SDK release can add APIs that need a newer Minga; this table says which.
Usage
defmodule MyExtension do
use Minga.Extension
option :enabled, :boolean, default: true, description: "Enable the extension"
command :my_command, "Does something useful",
execute: {MyExtension.Commands, :run}
keybind :normal, "SPC m x", :my_command, "Run my command"
@impl true
def name, do: :my_extension
@impl true
def description, do: "My cool extension"
@impl true
def version, do: "0.1.0"
@impl true
def init(_config), do: {:ok, %{}}
endLifecycle contract
Minga admits one complete validated artifact inventory for an extension source and keeps that code resident for the lifetime of the BEAM OS process. Disabling and restarting an extension stop its runtime and remove its source-owned contributions, but they do not unload modules. Editing path extension source, updating a Git extension, or changing a compiled user module takes effect only after a fresh Minga process starts.
Each extension has one stable lifecycle authority. It runs init/1, starts the child from child_spec/1, registers contributions, and only then publishes the runtime as running. The restart value on your top-level child spec is honored by that authority: :permanent restarts after any terminal exit, :transient only after abnormal exits, and :temporary never restarts. Minga starts the top-level runtime child as temporary internally so OTP and the lifecycle authority cannot both restart it.
def child_spec(config) do
Supervisor.child_spec({MyExtension.Supervisor, config}, restart: :transient)
endRuntime callbacks are declared with editor_event_handler/3. The supported families are :buffer_saved, :editor_action, and :source_unload. Callback exceptions, exits, unavailable code, and invalid returns are reported as explicit extension failures. A :source_unload callback runs during disable after new callback work is closed and before the runtime child and source contributions are removed. Keep it bounded and do not synchronously call extension start or stop from it.
Keep slow work out of callbacks. Run it in your extension's own supervised processes, started from child_spec/1, and publish results through the SDK APIs such as panels, overlays, badges, and sidebar snapshots. Minga cancels that work when your extension is disabled by stopping its runtime. Custom messages to the Editor process are not part of the SDK contract.
The engine and the standalone SDK compile the same declaration modules from sdk/lib/declarations. The standalone SDK also compiles API stubs that the engine does not use. The engine and SDK keep separate editor event-handler behaviours; the engine test suite checks that their callback families and signatures agree.
Model routes
A model route lets your extension add models to /model while Minga keeps running the agent turn: tools, approvals, retries, compaction, and history stay in Minga, and your route only streams model output. Register it from init/1 and keep the returned reporter:
def init(_config) do
{:ok, reporter} =
Minga.Extension.ModelRoutes.register(
id: "company_proxy",
module: CompanyProxy.Route,
display_name: "Company Proxy"
)
{:ok, %{reporter: reporter}}
endMinga checks your route's availability/2 when the user opens /model. When your extension learns about a change itself, for example right after the user signs in, report it through the reporter from any process:
Minga.Extension.ModelRoutes.report_status(reporter, {:ready, "me@example.com"})Subscription routes can do more. Pass short_name: (for example "Claude") to name the route inside sentences such as "Claude plan limit reached.", and setup_action: with a label and description to show a setup row in /model that runs your availability/2 check and shows your remedy text. When your route learns how much of a plan's limit windows is used, report it with report_usage/2; Minga shows it on the model's row and names the reset time when a limit is reached:
Minga.Extension.ModelRoutes.report_usage(reporter, [
%{kind: "five_hour", utilization: 0.82, resets_at: resets_at, status: :warning}
])Report an empty list when you have no usage data; Minga then shows nothing.
CompanyProxy.Route implements the MingaAgent.InferenceRoute behaviour: models/1, availability/2, stream/1, and classify_error/1. The route contract uses only Minga-owned values, so it stays stable when Minga changes its internal model library. See Model routes for a complete route.
What's included
Minga.Extensionbehaviour and DSL macros (option,command,keybind,modeline_segment,editor_event_handler,load_policy)Minga.Extension.Agentdeclarations for hooks, skills, MCP servers, slash commands, and semantic agent UIMinga.Extension.Overlay,Minga.Extension.Panel, andMinga.Extension.Badgefor overlays, panels, and file tree and tab badgesMingaEditor.Extension.Sidebarfor sidebar contributionsMinga.Extension.Storage,Minga.Extension.Diagnostics, andMinga.Extension.AIfor per-extension storage, diagnostics, and text generationMinga.Extension.Manifestfor the declaration snapshot of an extensionMinga.Extension.AgentAPIfor querying agent session stateMingaEditor.Extension.EditorAPIfor triggering editor actions from commandsMinga.Eventsfor subscribing to editor eventsMinga.Bufferpublic API typesMinga.Buffer.EditSourceandMinga.Buffer.EditDeltatypes for tracking edit origins and positionsMinga.Extension.ModelRoutesand theMingaAgent.InferenceRoutecontract for model routes
See the Extension API guide for callback ordering, source-owned work, artifact ownership, and update behavior.