Community plugins for task events

[bborn]

What

Makes TaskYou's event-hook system pluggable: community integrations install as self-contained, droppable directories instead of hand-placed scripts. Two capabilities so far — reactive hooks and user-invoked actions.

The gap

Task event hooks today are one script per event in a shared dir (~/.config/task/hooks/task.done). Two integrations that both care about task.done collide on the same file — no way to install several side by side.

Plugins

A plugin is a directory under ~/.config/task/plugins/ with a plugin.yaml manifest:

name: desktop-notify
version: 0.1.0
description: Native desktop notifications when a task finishes or needs you.
hooks:                      # fire automatically on events
  task.done: notify.sh
  task.blocked: notify.sh
actions:                    # user-invoked, on demand
  - id: test
    label: Send a test notification
    command: test-notify.sh

Drop the directory in and it's live. Any number of plugins can handle the same event, and all of them run — alongside the legacy single-script hook, which still works.

cp -R examples/plugins/desktop-notify ~/.config/task/plugins/
ty plugins list
ty plugins run desktop-notify test 42     # run an action against task #42

How it works

• internal/hooks/plugins.go — manifest schema + forgiving discovery/validation. A malformed manifest, missing script, nameless plugin, or bad action entry is skipped (surfaced in ty plugins list / the daemon log), so one bad community plugin can't break a user's pipeline. A plugin needs ≥1 usable hook or action.
• Hooks — on each event the Runner fans out to the legacy hook plus every matching plugin, concurrently in the background. Plugin hooks get TASK_PLUGIN_NAME / TASK_PLUGIN_DIR and run with cwd = the plugin dir. (Also moved the 30s timeout into the goroutine so a hook isn't cancelled the instant Run() returns.)
• Actions — internal/hooks/actions.go: RunAction runs an action synchronously (60s) with the task+plugin env; FindAction resolves plugin/action. Exposed via ty plugins run <plugin> <action> [task-id]. This is the shared runner all action surfaces use.
• ty plugins list / ty plugins dir to inspect what's installed.
• examples/plugins/desktop-notify/ — a complete plugin (hooks + an action).
• docs/plugins.md + README — manifest format and authoring guide.

Built entirely on the existing hooks pipeline; no changes to the executor launch path.

Roadmap (discussed, not in this PR)

• Action UI surfaces — a detail-view picker and command-palette entries, both on the RunAction runner above.
• Plugin panes — turning the detail view's aux/shell slot into a tabbed container so a plugin (or the user) can add a command pane without touching the executor's "one per task" model. This is a focused refactor of detail.go and will land as its own PR.

Scope note

Plugins fire for the events the Runner dispatches today (task.started, task.done, task.blocked, task.failed, task.auth_required), documented in docs/plugins.md.

Test plan

• go test ./internal/hooks/ — passing. Covers hook discovery (valid/multiple/sorted/missing-dir/invalid-skipped/partial-drop), an end-to-end fan-out test (legacy hook + two plugins fire on one event, plugin env asserted), and action validation + RunAction env injection (with and without a task) + FindAction.
• go build ./..., go vet, gofmt clean.
• golangci-lint run (v2.8.0, matching CI) — 0 issues.
• Verified ty plugins list / ty plugins run against an installed copy of the example plugin.

🤖 Generated with Claude Code