Build your first plugin

Before you begin

You need the host CLI supplied with your Lyre build, Node.js/npm, and familiarity with TypeScript. Install the desktop CLI integration, then reopen your shell and run lyre-foundation --help. Windows installs %USERPROFILE%\.local\bin\lyre-foundation.cmd; macOS and Linux install ~/.local/bin/lyre-foundation. If PATH is unavailable, invoke that full path (PowerShell: & "$HOME\.local\bin\lyre-foundation.cmd" --help). Use the CLI from this Lyre build; these author commands require the updated build. Start with a disposable development host and a plugin that does not read files or call a paid service. The generated project matches the CLI’s SDK version.

Create and check the scaffold

lyre-foundation plugin init ./my-plugin --template greeting
cd my-plugin
npm install
npm run typecheck
lyre-foundation plugin check . --json

Use an empty directory. Initialization writes files but does not install dependencies. Review the generated package before running the package manager. The scaffold includes a greeting surface and a typed request between the client and host.

Choose panel for a workspace panel and its Command Center action, lifecycle for a server-side turn observer with cleanup and a pure-handler test, or acp-provider for an external coding agent. The default remains greeting. Replace the ACP executable placeholder before installing it.

plugin check validates the manifest, version requirements and source imports, then compiles in memory. It does not connect to a host, run plugin entries or preparation scripts, install dependencies, or enable plugins. Run typechecking separately. Static success does not verify dynamic registrations, assets, runtime behavior or provider readiness.

Keep three responsibilities separate

index.client.tsx and client/

Register and render the interface. Respect the supplied theme and compact layout.

index.server.ts and server/

Register and implement host behavior. Keep credentials and privileged operations here.

shared/

Define typed requests, validation schemas and plain data shared by both sides.

Keep the SDK imports and dependency names created by the scaffold. Its shared, client and server entry points match the CLI version used to generate your plugin; do not rename them when naming your own plugin.

Make one small change

Edit the generated greeting in server/greeting.ts, then run type checking. Keep the shared response shape compatible with the client. For a new input, update its shared validation schema and both consumers together.

npm run typecheck
lyre-foundation plugin check .
lyre-foundation plugin install .
lyre-foundation plugin logs my-plugin
lyre-foundation plugin reload my-plugin

Enable the plugin system only on your chosen development host after reviewing its configured sources. See installation and trust.

Connect an agent tool

For a tool an agent can call, use the existing MCP connection: implement an MCP stdio or HTTP server, then add it in the selected computer's Tools settings. For a local server, use an absolute command and the arguments that start its MCP transport. Keep credentials in host-side environment values or headers. Saving applies to agents started afterward; it does not prove the connection works. Check the chosen provider's MCP support and test a harmless tool call. See Build an integration.

UI and lifecycle contributions use Lyre plugins; coding agents use ACP providers. Catalog-only Extensions are separate. Choose the interface matching your task before adding a new runtime.

Optional DeepSeek Harness provider

The source example at app/plugin-examples/deepseek-harness registers DeepSeek Harness through the existing ACP adapter. Its README gives pinned installation and host launcher setup using LYRE_DSH_ENTRYPOINT. It launches Node directly, including on Windows, and is never installed or enabled automatically.

Use the Lyre build containing resume-only ACP support. The adapter prefers session load when available and otherwise uses advertised resume support. Harness is a rapidly changing preview with no transcript replay or session forks. Local protocol fixtures pass; actual Harness startup and credentialed model work remain unverified. Review the upstream setup guide before configuring its model credentials on the host.

Test the lifecycle, not just the happy path

• Open the surface on a narrow phone and a desktop, in light and dark themes.
• Test invalid input, a failed request and a disconnected host.
• Disable and reload the plugin. Dispose timers, listeners and resources in contribution cleanup.
• Verify no secrets appear in client responses or logs.

Keep a README, version requirements, license and reproducible setup with your source. Test a pinned revision before asking others to install it. Broad extension sandboxing is not supplied by the current plugin runtime.