@vanillagreen/pi-background-tasks

Pi extension for explicit non-blocking background shell tasks, log tails, and completion wakeups.

Packages

Package details

extension

Install @vanillagreen/pi-background-tasks from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@vanillagreen/pi-background-tasks
Package
@vanillagreen/pi-background-tasks
Version
2.0.1
Published
Sep 5, 2026
Downloads
1,221/mo · 615/wk
Author
vanillagreencom
License
MIT
Types
extension
Size
793.2 KB
Dependencies
0 dependencies · 4 peers
Pi manifest JSON
{
  "extensions": [
    "./extensions/background-tasks.ts"
  ],
  "image": "https://raw.githubusercontent.com/vanillagreencom/kendex/main/pi-extensions/pi-background-tasks/assets/spawn-tasks.png",
  "appendSystem": "./instructions.md"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@vanillagreen/pi-background-tasks

A Pi extension for shell commands that run while the conversation continues. It supports builds, development servers and log monitors.

Spawning background tasks Inline mini-dashboard

Install

  • npm: pi install npm:@vanillagreen/pi-background-tasks.
  • kendex: add the declaration below to the project's kendex.toml, or to ~/.config/kendex/kendex.toml for user scope. Run kendex update-pi.
[pi-extensions."@vanillagreen/pi-background-tasks"]
source = "kendex"

Restart Pi after installation. Use kendex update-pi --check to preview the installation.

Features

  • Start, inspect and stop background commands.
  • Move configured blocking commands into background tasks.
  • Notify the agent when a task exits or produces selected output.
  • Read full logs and task history in the dashboard.
  • Optionally reduce task CPU and disk priority.

How it works

The agent starts a command with the background task tool. The extension runs the command separately and saves its output to a log. It shows task status beside the editor. When the command exits or matches a notification rule, it sends the agent a message with recent output and the log path.

Settings

The settings editor writes project values to .pi/settings.json. The default user file is ~/.pi/agent/settings.json. PI_CODING_AGENT_DIR changes the user directory. Package values are stored under kendex.extensionManager.config["@vanillagreen/pi-background-tasks"].

Open /extensions:settings; settings appear under the Background Tasks tab. Project settings in .pi/settings.json apply only after Pi marks the workspace trusted.

  • enabled: package toggle; glyphStyle picks Unicode or ASCII symbols, and pi-tool-renderer's global override wins when set.
  • Auto-backgrounding: autoBackgroundBash, autoBackgroundPatterns, forcedBackgroundWindowSeconds, forcedBackgroundNotifyOnOutput.
  • Execution: defaultTimeoutSeconds, forceKillGraceMs, and the resourceControl* group (resourceControlEnabled turns it on, resourceControlMode picks the mechanism, the rest set weights, niceness and where controls apply).
  • Wakes and output: outputSettleMs, outputAlertMaxChars, outputWakeBudgetMaxWakes, outputWakeBudgetMaxBytes, outputBufferMaxChars, logTailMaxChars.
  • UI: showWidget, widgetPlacement, widgetDefaultMode, widgetFinishedRetentionSeconds, toolRenderMode, toolExpandedLogLines, dashboardOutputMaxLines.
  • Shortcuts: backgroundBashShortcut, widgetToggleShortcut, dashboardShortcut; none disables one, and a change takes effect on restart.
  • Storage: taskDir; the PI_BG_TASK_DIR environment variable overrides it.

Maintainer notes are in DEVELOPMENT.md. The package is kendex's own, based on the MIT-licensed @ifi/pi-background-tasks; see THIRD_PARTY_NOTICES.md.