Extending AgentDE

Two ways to add to AgentDE:

Contents: Native extensions · Hooks · The host · Saving data · Example · Adding it to a build · Widgets · Ticket providers · Link rules · Themes and palettes · JSON plugins

Native extensions

The API is the AgentDEKit library (Sources/AgentDEKit/):

An extension is a class with an id (stable: it namespaces the extension’s saved data) and a name (shown in Settings). Every hook has a default that does nothing, so an extension implements only what it adds. The app creates extensions at launch, in extensions.json order, calls start(host:) after saved state is loaded and stop() at quit. Hooks are called on the main thread.

Hooks

TabInfo is a tab as extensions see it: id, groupID, kind (claude, codex, shell, command, files), folder, groupFolder, title, agentSession (Claude’s session id or Codex’s thread id), agentPresent, state (none, working, needsYou, doneUnseen), viewerItem, and isAgent.

The host

AgentDEHost is the app’s own observable state, so a SwiftUI view that reads it updates when it changes. Main thread only.

Per-tab values and settings

Add new settings fields with defaults, so older saved settings still decode.

An example extension

A package agentde-hello with one library target, depending on AgentDEKit:

// Sources/AgentDEHello/HelloExtension.swift
import AgentDEKit
import SwiftUI

struct HelloSettings: Codable { var greeting = "Hello" }

public final class HelloExtension: AgentDEExtension {
    public let id = "hello"
    public let name = "Hello"
    private var host: AgentDEHost?

    public init() {}

    public func start(host: AgentDEHost) { self.host = host }

    // Every tab's shell gets HELLO_TAB.
    public func launchEnvironment(for tab: TabInfo) -> [String: String] { ["HELLO_TAB": tab.id.uuidString] }

    // Group → New → Say hello: opens a shell tab and greets.
    public func newMenuItems(for group: GroupInfo) -> [ExtensionAction] {
        [ExtensionAction("Say hello", symbol: "hand.wave") { [weak self] in
            guard let self, let host, let tab = host.openTab(kind: .shell, in: group.id, folder: nil, title: "hello") else { return }
            let greeting = host.settings(HelloSettings.self, for: self, fallback: HelloSettings()).greeting
            host.type("echo \(greeting)\r", into: tab)
        }]
    }

    // Wiki pages open in the viewer.
    public var linkRules: [LinkRule] { [LinkRule(pattern: #"https://wiki\.example\.com/page/\w+"#, marker: "wiki.example.com/page/")] }
}

// Package.swift
// swift-tools-version:5.10
import PackageDescription

let package = Package(
    name: "agentde-hello",
    platforms: [.macOS(.v14)],
    products: [.library(name: "AgentDEHello", targets: ["AgentDEHello"])],
    dependencies: [.package(path: "../agentde")],
    targets: [.target(name: "AgentDEHello", dependencies: [.product(name: "AgentDEKit", package: "agentde")])]
)

Adding it to a build

Put it beside agentde/ (or give its repo, and the build clones it there) and add an entry to agentde/extensions.json (or a copy passed with make EXTENSIONS=…):

{
  "extensions": [
    { "package": "../agentde-widgets", "product": "AgentDEWidgets", "create": "WidgetsExtension()" },
    { "package": "../agentde-hello", "repo": "https://github.com/you/agentde-hello", "product": "AgentDEHello", "create": "HelloExtension()" }
  ]
}

scripts/assemble.py turns the file into a small package (.build/app-package) whose main.swift calls AgentDEMain.run(extensions: [...]), and scripts/build-app.sh builds and bundles it. A workspace that builds its own app instead calls AgentDEMain.run(extensions:) from its own executable and sets APP_PACKAGE, APP_PRODUCT and APP_HELPERS for build-app.sh.

Widgets

The sidebar widget spot belongs to the Widgets extension (agentde-widgets). Another extension adds widgets by depending on AgentDEWidgets and conforming to WidgetProvider:

import AgentDEKit
import AgentDEWidgets
import SwiftUI

extension HelloExtension: WidgetProvider {
    public var widgets: [WidgetDefinition] {
        [WidgetDefinition(id: "hello.clock", name: "Clock") {
            AnyView(WidgetCard { Text(Date.now, style: .time).font(.title) })
        }]
    }
}

The menu lists widgets from every WidgetProvider in load order.

Ticket providers

A workstream’s tickets are tracker-neutral: a key (ENG-123), owner/repo#12, or a link to Linear, Jira, GitHub, GitLab or any https page. A TicketProvider looks them up so the panel can show state, priority and title.

TicketInfo carries identifier, title, url, and optionally state, stateType, colorHex and priority (1 urgent to 4 low, 0 none). TicketRow draws one. Return providers from ticketProviders; agentde-linear is a complete example.

Link rules

A LinkRule makes matching links open in the tab’s viewer instead of the browser, and (with the Workstreams extension) count as artifacts in the panel.

Claude artifact links are built in.

Themes and palettes

Theme has window, sidebar, text, secondary, muted, border, hover, selected (SwiftUI colors), terminalBackground, terminalForeground, terminalSelection (NSColors), and an optional outline that outlines the active tab and group. Views read the current theme from @Environment(\.theme).

JSON plugins

A plugin is a folder in ~/.config/agentde/plugins/ (a renamed build uses its own data folder) holding a plugin.json. Plugins are read once at launch, in folder-name order; one whose plugin.json doesn’t parse is skipped and logged in the debug log. Every field but name is optional.

A plugin widget’s id in the menu is plugin.<id>. The example in examples/hello-plugin adds a page widget, a command widget, a link rule, a theme, a palette and an agent:

{
  "name": "Hello",
  "widgets": [
    { "id": "hello.page", "name": "Hello", "page": "widget.html" },
    { "id": "hello.disk", "name": "Disk", "command": "df -h / | tail -1 | awk '{print $4 \" free of \" $2}'", "every": 300 }
  ],
  "links": [
    { "pattern": "https://gist\\.github\\.com/[\\w-]+/[0-9a-f]{20,}", "marker": "gist.github.com/" }
  ],
  "themes": [
    { "id": "hello.dusk", "name": "Dusk (always dark)", "alwaysDark": true,
      "dark": { "window": "#1B1B2F", "sidebar": "#16162A", "text": "#ECEAF6", "...": "..." } }
  ],
  "palettes": [
    { "id": "hello.sea", "name": "Sea", "colors": ["#0B7285", "#1098AD", "#15AABF", "#3BC9DB", "#66D9E8", "#99E9F2", "#C5F6FA", "#495057"] }
  ],
  "agents": [
    { "id": "hello.gemini", "name": "Gemini", "command": "gemini" }
  ]
}

To try it: cp -R examples/hello-plugin ~/.config/agentde/plugins/hello, restart AgentDE, and pick Hello in the sidebar widget’s menu.