Documentation

Extending without code

Launcher commands, the Notch and task widgets, in three TOML files.

On this page

Three drop-in files

Not every extension needs a binary. Three directories under ~/.config/tde/ are scanned at startup, and dropping a TOML file in any of them adds real functionality to the desktop.

Path	Adds
`commands/*.toml`	Rows in the Launcher's command palette.
`notch.toml`	Chips on the Notch at the top of the screen.
`widgets/*.toml`	Action buttons on a My Loop task.

All three are read defensively: a file that fails to parse is skipped, and the built-in defaults stay available. A broken extension can annoy you, but it cannot break the desktop.

Commands

Any .toml file in ~/.config/tde/commands/ adds rows to the Launcher (Alt+Space). Files are read in sorted order and merged after the built-ins.

~/.config/tde/commands/deploy.toml

[[commands]]
app = "Deploy"
title = "Ship staging"
action = "cmd:make deploy-staging"
icon = "🚢"

[[commands]]
app = "Deploy"
title = "Open the dashboard"
action = "url:https://dash.internal/deploys"

[[commands]]
app = "Deploy"
title = "Connectors"
action = "control:connectors"

Field	Required	Meaning
`app`	yes	The owning app name. The palette groups and labels by it.
`title`	yes	The action name.
`action`	yes	What to run — see the grammar below.
`icon`	no	A glyph for the row. Defaults to `📦`.

An entry with any of the three required fields blank is skipped. Rows are shown as App: Title and matched against "App Title", so typing either the app name or a word from the action finds it.

This is exactly the mechanism tde-app register uses to add a built app to the Launcher, so an app package and a hand-written command file are indistinguishable to the desktop.

The action grammar

Shared by all three files (widgets excepted — they carry prompts, not actions).

Form	Meaning
A built-in id	Open a native TDE surface.
`cmd:<shell command>`	Run in a terminal window, then drop into an interactive shell so output stays on screen.
`app:<catalog name>`	Launch an installed Store app.
`url:<address>`	Open in TDE Browser.
`control:<panel-id>`	Deep-link into a Control Center panel.
`myloop:<section>`	Deep-link into a My Loop section.

Built-in ids:

text

launcher   terminal  shell     files     editor    browser
sheets     docs      api       redis     vercel    webhook
database   mermaid   aichat    email     hosts     process
container  env       control   myloop    store     git
pr         wiper

An unrecognised action pops a toast naming it, so a typo is visible rather than silent.

The Notch

~/.config/tde/notch.toml replaces the six built-in Notch chips. Control Center → Notch writes this same file, so you can start in the UI and keep editing by hand.

~/.config/tde/notch.toml

[settings]
enabled = true
icons_only = false

[[items]]
icon = "🚀"
label = "Apps"
action = "launcher"

[[items]]
icon = "💻"
label = "Shell"
action = "terminal"

[[items]]
icon = "🗄"
label = "Backups"
action = "cmd:restic snapshots"

[[items]]
icon = "📊"
label = "Grafana"
action = "url:https://grafana.internal"

Key	Meaning
`settings.enabled`	`false` stops the Notch being drawn or hit-tested. Defaults to `true`.
`settings.icons_only`	`true` hides labels even when they would fit.
`items[].icon`	Optional. Without one, the label's first letter stands in.
`items[].label`	The chip text and tooltip.
`items[].action`	The action grammar above.

Items with an empty action are dropped. If that empties the list, the built-in defaults come back — you cannot configure yourself into an empty Notch.

See Notch, taskbar and launcher for when the Notch is and is not drawn.

Task widgets

A widget is a button on a My Loop task's detail screen (My Loop → Tasks → open a task). Clicking it injects a prompt into the task as a comment, and the task's configured agent picks that comment up on its next run. Widget-injected comments are marked with 🧩 in the task Activity feed.

Drop one file per widget in ~/.config/tde/widgets/. A file whose id matches a built-in overrides it; a new id is appended.

~/.config/tde/widgets/deploy.toml

id = "deploy"
label = "Deploy"
icon = "🚀"
requires = "flyctl"
install_hint = "brew install flyctl"
prompt = """
Deploy the worktree at {worktree} to staging.
Report the resulting URL in the activity for task {task} ({tracker}).
Save any screenshots under {demo_dir}.
"""

Field	Required	Meaning
`id`	yes	Stable identifier. Matching a built-in id replaces it.
`label`	yes	Button text.
`prompt`	yes	The agent prompt, with placeholders expanded.
`icon`	no	Glyph shown before the label.
`requires`	no	A CLI that must be on `PATH` for the widget to run.
`install_hint`	no	Shown on the button instead of running while `requires` is missing.

Placeholders

Placeholder	Expands to
`{worktree}`	Absolute path to the task's git worktree, or the project root.
`{demo_dir}`	The suggested output folder inside the worktree.
`{task}`	The task title.
`{tracker}`	The tracker id, for example `LIG-42`.

One widget ships with TDE: Demo, which asks the task's agent to visually verify the change with agent-browser and capture it as screenshots or an optimized WebM video. It is supervised rather than a plain prompt — TDE tracks progress, enforces a five-minute recording limit, and writes each run to its own timestamped directory in the worktree.

It declares requires = "agent-browser", so if that CLI is missing the button shows the install hint instead of starting a partial capture. Video capture also needs ffmpeg on PATH.

Give a file the id demo and you replace this widget with your own.

What this does not cover

Skills, prompts, deliverables and bots are also authored without writing code, but they live in TDE's database and are edited through Control Center and My Loop rather than as files under ~/.config/tde/. See Skills, prompts and deliverables and Bots.

Configuration — these files in the config reference.
Notch, taskbar and launcher — where commands and Notch items show up.
Your first app — when TOML is no longer enough.