pi-bg-tasks

A friendly pi package that adds a /bg command for running shell commands in the background with tmux.

Use it for dev servers, watchers, long-running scripts, or anything you want to keep out of the main chat while pi keeps working.

Features

• /bg <command> starts a command in a detached tmux session from the current project directory
• /bg opens an interactive menu for recent and running background commands
• The LLM can launch, inspect, and kill background tasks itself via the start_bg_task, bg_task_status, and stop_bg_task tools (e.g. "start npm run dev in the background, wait until it's ready, then run the e2e tests")
• A small widget appears above the editor while commands are running in the current directory
• Press ↑ from the main chat to peek at the latest logs for a running background command
• Press ↑ again while viewing logs to close the log viewer and return to chat
• Recent commands are remembered per working directory so you can quickly rerun them later
• Logs auto-refresh while open
• Running commands can be killed or attached from the UI

Requirements

• pi with extension/package support
• tmux installed and available on your PATH
• A shell environment that can run your command with bash -lc

Install

From npm

After this package is published:

pi install npm:@zackify/pi-bg-tasks

Then reload pi:

/reload

Manual install

Copy the extension into your global pi extensions directory:

mkdir -p ~/.pi/agent/extensions
cp extensions/bg.ts ~/.pi/agent/extensions/bg.ts

Or install it only for one project:

mkdir -p .pi/extensions
cp extensions/bg.ts .pi/extensions/bg.ts

Then reload pi:

/reload

Usage

Start a command directly:

/bg npm run dev

Or open the menu:

/bg

From the menu:

• Enter on New command… or a recent command fills the editor with /bg ...
• Enter on a running command opens its logs
• k kills the selected running command
• a attaches to the selected tmux session
• Esc closes the menu

When a background command is running in the current directory, pi shows a small status widget above the editor. From the main chat, press ↑ to view its logs. While the log viewer is open, press ↑ again to close it.

LLM tools

The extension exposes three tools the model can call directly, so you can just ask in natural language and let the agent keep working while the task runs:

• start_bg_task — takes a command string and launches it the same way /bg <command> does. Returns the tmux session id and log file path so the model can find it later.
• bg_task_status — checks whether a background task is still actively running, how long it has been up, and the tail of its log output. Pass a command to check a specific task, or omit it to list every background task in the current working directory. Optional logLines (default 40, max 500, set to 0 to skip logs).
• stop_bg_task — takes the same command string and kills the matching background task in the current working directory. If nothing matches it returns the list of currently running tasks so the model can retry with the right name.

Matching is scoped to the current working directory, so the model cannot accidentally touch a task running in another project.

Why this matters for the agent

Without background tasks, an AI agent that needs a dev server, watcher, or long build has two bad options: block the entire turn on a process that never exits, or fire-and-forget and lose all visibility. These tools fix both problems:

• Non-blocking startup. start_bg_task returns immediately with a session id and log file. The agent can move on to running tests, editing code, or hitting an endpoint instead of hanging on npm run dev.
• Active polling. bg_task_status lets the agent loop "start → poll logs → continue when ready" without a human in the middle. It can confirm a server printed Listening on :3000, detect a compile error in a watcher, or notice that a long migration finally finished, all by re-reading the log tail.
• Self-healing cleanup. stop_bg_task makes the agent responsible for tearing down what it started. Combined with the cwd-scoped matching, the model can safely manage multiple tasks across a session without leaking processes.
• Stable references. Tasks are addressed by the exact command string the agent used to start them, so the model does not have to track opaque session ids across tool calls — it just remembers what it asked for.

Example prompts:

• "Start npm run dev as a background task, wait until it's listening, then run the e2e tests and stop it when you're done."
• "Is the pnpm build --watch task still running? Show me the last 100 lines of its logs."
• "List every background task running in this project."
• "Kill the npm run dev background task."

History and logs

The extension stores its local state under ~/.pi/agent/:

• bg-cache.json remembers recent /bg commands by working directory
• bg-meta/ stores metadata for active tmux sessions
• bg-logs/ stores command log files

This state stays on your machine. It is not included in this package and should not be committed.

Privacy notes

This repository does not include personal command history, logs, hostnames, tokens, or machine-specific configuration. The extension itself stores command history locally so it can offer recents; avoid running commands that include secrets if you do not want them saved in your local history file.

Troubleshooting

tmux is not installed

Install tmux with your system package manager, then reload pi.

I do not see logs with the up arrow

Make sure a /bg command is currently running in the same working directory as your pi session. You can also run /bg to open the menu and select a running command.

A command exits immediately

Open the logs with ↑ or /bg to see the command output. The command runs from the current project directory using bash -lc.

Publishing

When you are ready to publish manually:

npm publish --access public

This repository also includes the same release workflow style as pi-port-forward: create a GitHub release named like v1.2.3, add an NPM_TOKEN repository secret, and GitHub Actions will publish that version to npm with provenance.

Files

• extensions/bg.ts — extension source
• package.json — pi package metadata for @zackify/pi-bg-tasks, including the pi-package keyword
• .github/workflows/publish.yml — optional npm publish workflow for GitHub releases