Plugin Development

The Tribunus Desktop Plugin SDK enables developers to extend the application with custom capabilities. Plugins are self-contained packages that register tools, agents, and workflow steps with the Desktop runtime. The SDK source lives at packages/plugin/src/.

Plugins are sandboxed by the Electron main process: each plugin declares the capabilities it needs (file system access, network, subprocess execution), and Desktop enforces the boundary through the secure IPC bridge. Capabilities outside the declared scope are blocked and logged.

Plugin Structure

A plugin is a standard npm package with a package.json manifest that declares a tribunus field pointing to the plugin entry point. The entry point exports a definePlugin call that registers the plugin’s contributions:

import { definePlugin } from '@tribunus/plugin-sdk';

export default definePlugin({
  id: 'my-custom-tools',
  name: 'My Custom Tools',
  capabilities: ['fs:read', 'network:fetch'],
  tools: [ /* ... */ ],
  agents: [ /* ... */ ],
  steps: [ /* ... */ ],
});

Defining Tools

Tools are the fundamental unit of plugin capability. Each tool implements an async function that receives typed arguments and returns typed results. The SDK handles schema validation via Zod, serialization, and error wrapping:

import { tool, z } from '@tribunus/plugin-sdk';

const summarizeTool = tool({
  id: 'text.summarize',
  name: 'Summarize Text',
  description: 'Generate a concise summary of the given text.',
  input: z.object({ text: z.string() }),
  output: z.object({ summary: z.string() }),
  async execute({ text }) {
    const summary = await callLLM(`Summarize: ${text}`);
    return { summary };
  },
});

Tool schemas are exposed to the Desktop agent runtime for automatic validation, code-completion in the agent prompt builder, and display in the tool browser.

Registering Agents

Plugins can define agent configurations that appear in the Desktop agent picker. An agent configuration bundles a system prompt, a tool set, a model backend preference, and optional safety constraints:

import { agent } from '@tribunus/plugin-sdk';

const reviewAgent = agent({
  id: 'code-reviewer',
  name: 'Code Reviewer',
  prompt: 'You are a thorough code reviewer. Analyze pull requests for bugs, security issues, and style problems.',
  tools: [summarizeTool, gitDiffTool, lintTool],
  model: 'gpt-4o',
});

Workflow Steps

Workflow steps chain tool calls with conditional branching. Steps can declare inputs from previous step outputs, making it possible to build multi-step pipelines:

import { step } from '@tribunus/plugin-sdk';

const reviewPipeline = step({
  id: 'review-pr',
  name: 'Review Pull Request',
  steps: [
    { tool: 'git.fetchDiff', input: { prNumber: '$pr' } },
    { tool: 'code-reviewer.analyze', input: { diff: '$0' } },
    { tool: 'text.summarize', input: { text: '$1' }, condition: 'needsSummary' },
  ],
});

The $pr, $0, $1 syntax references pipeline inputs and preceding step outputs. The condition field gates execution on a runtime check.

Plugin Lifecycle

Plugins are loaded at Desktop startup from the user’s plugin directory (~/.tribunus/plugins/). The SDK validates the manifest, resolves dependencies, and registers all contributions before the agent runtime starts. Plugins can also be hot-loaded at runtime through the Plugin Manager UI, subject to the user’s security preferences.

A plugin marketplace is coming soon, allowing published plugins to be discovered, rated, and installed from within the Desktop Settings panel.