Extending

Plugins

octomux is a metaharness: a plugin is an npm package listed in ~/.octomux/octomux.yml whose apply(ctx) runs once at boot and registers workflow kinds, integration providers and harnesses.

Why they exist

Nothing octomux ships is special-cased. Claude Code, Jira and the nightly log-triage job all register through the same registries a plugin gets — so the built-ins are the proof that your package is possible.

The three registrars

Registrar	Use it for	Ships today
`ctx.harnesses`	A coding agent backend — how it launches, resumes and reports back	claude-code, cursor
`ctx.integrations`	Reacting to task lifecycle events and pushing to an external system	jira, linear, slack, telegram
`ctx.workflows`	A new kind of scheduled or looped job, with its own config form and run history	7 kinds

Everything a plugin registers is namespaced under its manifest row id, so two plugins — or a plugin and a built-in — can never collide. A plugin can add discord; it can never overwrite slack.

The easiest plugin: a kind

A “kind” is a JSON preset for the existing scheduled-session engine — a cron trigger, a prompt and a config form. Ship kinds/<name>.json in a package named octomux-kind-<name>, list it in the manifest, and it appears in the UI. No apply(), no server code.

Installing one

# ~/.octomux/octomux.yml
plugins:
  - id: myplugin          # local namespace
    name: my-plugin-pkg   # npm package, or an absolute path for dev

octomux start
octomux doctor            # confirms it loaded, or says why not

Security

Plugins are not sandboxed. They run in-process with full Node privileges — a plugin can read your filesystem and make network calls. Install them the way you would install any dependency that runs on your machine: read the source first. Namespacing prevents collisions; it is not a security boundary.

See the Plugin API for the full context shape, or the plugin ideas list for 17 scoped starting points with effort estimates.