Extensions

Shape Excalibur with declarative YAML or the TypeScript SDK — plus MCP servers and LSP diagnostics. Even the built-ins are extensions.

Excalibur is an extensible runtime from day one. Everything — including the built-in catalogs — is an extension, loaded through the same registry, so the product works identically whether or not you add your own.

Two ways to extend

Declarative (YAML / Markdown) — for how your team works, no code. Ten contribution types:

Type	What it adds
`workflow`	A phase-based recipe (see Workflows).
`methodology`	Roles, prompts and quality bars a workflow runs with.
`question_pack`	Question sets for Discovery and planning.
`prompt_template`	Reusable prompts → invocable as `/commands`.
`artifact_template`	Output shapes (plans, reports, summaries).
`report_template`	Daily/weekly report formats.
`role_definition`	Named agent roles (reviewer, architect, …).
`policy_preset`	Bundled safety/approval defaults.
`model_routing`	Which model handles which task/path.
`command_mapping`	Map a command to a workflow + autonomy.

Programmatic (TypeScript SDK) — to connect your systems:

import { defineExtension } from '@excalibur-oss/extension-sdk'

export default defineExtension({
  workItems:  [linearProvider],     // a custom work-item source
  channels:   [slackChannel],       // where summaries post
  mcpServers: [githubMcp],          // external tools → the agent
  tools:      [deployTool],         // your own native tools
  policies:   [budgetGuard],        // policy evaluators
})

Interfaces include work-item providers, communication channels, model providers, agent adapters, tools, policy evaluators, context sources, hooks and MCP servers.

The manifest

Each extension declares an excalibur.extension.yaml:

id: acme-secure-feature
kind: declarative
contributes:
  workflows: ["./workflows/secure-feature.yaml"]
  policyPresets: ["./policies/acme-standard.yaml"]
permissions:
  filesystem: read
  network: { allowedHosts: [] }     # none by default
configSchema: ./config.schema.json

MCP & LSP

MCP servers — the tools of any Model Context Protocol server flow straight to the agent, with the manifest's permissions applied. Add one from the signed registry, with OAuth where the server needs it.
LSP diagnostics — Excalibur auto-installs and starts real language servers (typescript-language-server, gopls, pyright, …) and feeds actual compiler errors to the agent and to review, so fixes anchor in real diagnostics, not hallucinated lines. Per-edit formatters (prettier · biome · gofmt · rustfmt) run automatically too.

Custom agents

Define self-contained agent personas as Markdown files in .excalibur/agents/<name>.md. The front-matter sets the persona's role, model, provider, temperature, an allowed-tools list and permissions; the body is its system prompt. The tools allowlist narrows the role's floor (deny wins), so a persona can never exceed your safety policy.

excalibur agents list / show <name> / init <name>
excalibur run --agent reviewer "audit the auth module"   # or switch in-shell with /agent

IDE extension

A VS Code / Cursor / Windsurf extension bridges your editor to Excalibur over the Agent Client Protocol (ACP): it spawns excalibur acp and streams the run — assistant messages, tool calls, the live plan, per-file diffs and commands — into a panel, with inline approvals. Install the .vsix (or the Marketplace once published); editors that host ACP agents natively (Zed, JetBrains, Neovim) can point straight at excalibur acp.

Managing extensions

In the shell (/extensions …) or as CLI commands:

excalibur extensions list
excalibur extensions validate
excalibur extensions create workflow my-team-process
excalibur extensions enable <id>
excalibur extensions install <path>

Built-ins are packs too. The default 14 workflows, 14 methodologies, question packs, prompts, presets and roles ship as built-in extension packs consumed through the registry — which is why the system behaves identically with zero user extensions, and why your additions compose cleanly on top.

Enterprise governs extensions centrally: version-locking, permission enforcement, encrypted secrets, and policies for which extensions a team or repo may enable. See Enterprise.

Workflows — the most common thing to customize.
Models & providers — add a provider or passthrough adapter.