background-tasks is an experimental Bun workspace for local background task orchestration in agent workflows. It provides a JSON-first CLI, reusable task lifecycle primitives, and opencode integrations for long-running local commands.
- Maturity: experimental
- Maintainer model: solo-maintained
- Repository visibility: private until explicitly approved for public access
- Package channel: npm is the intended first channel, but packages are not published yet
Use this project when an agent needs to start, inspect, stop, restart, or stream logs from local background processes through machine-stable JSON. Do not use it as a hosted job runner, remote execution service, credential vault, or multi-tenant scheduler.
The root workspace package is private. The publishable package set is:
@skastr0/background-tasks-core: task lifecycle, log, and control-plane primitives@skastr0/background-tasks: npm runner package for thebackground-tasksCLI@skastr0/background-tasks-darwin-arm64: macOS arm64 standalone CLI binary@skastr0/background-tasks-darwin-x64: macOS x64 standalone CLI binary@skastr0/background-tasks-linux-arm64: Linux arm64 standalone CLI binary@skastr0/background-tasks-linux-x64: Linux x64 standalone CLI binary@skastr0/background-tasks-opencode: OpenCode server plugin and TUI integration
apps/cli is a private source workspace. The public CLI package uses a Node launcher that delegates to one of the platform binary packages.
The first public release should publish npm packages only after repository visibility, npm trusted publishing or registry credential setup, package dry-runs, and maintainer approval are complete. GitHub Releases and Homebrew distribution are deferred.
See PUBLISHING.md for the release authority model, package order, OpenCode plugin install shape, and CLI binary topology.
Until packages are published, install from source:
bun install
bun run build:binary
bun run install:localRequirements:
- Bun 1.3 or newer
- macOS or Linux for the current local-process workflow
After publication, the intended npm runner entrypoints are:
npx @skastr0/background-tasks --version
bunx @skastr0/background-tasks --version
pnpm dlx @skastr0/background-tasks --versionThe CLI is JSON-first. Domain data is passed as a single JSON payload, while flags only control execution behavior.
Payload input modes:
background-tasks start '{"id":"bg_demo","command":"sleep","args":["60"]}'
background-tasks start @payload.json
cat payload.json | background-tasks start -Execution flags:
--output auto|inline|artifact--wait--stream--timeout <seconds>--concurrency <n>
Success is written to stdout:
{
"ok": true,
"command": "status",
"data": {}
}Expected failures are written to stderr with exit code 1:
{
"ok": false,
"command": "status",
"error": {
"type": "TaskNotFound",
"message": "task not found: bg_missing",
"details": {
"id": "bg_missing",
"hint": "Run list to discover known task ids.",
"retryable": false
}
}
}Core commands:
startsubmits and starts one task, or a batch of tasks.statusinspects one task.listlists tasks with optionalids,status,tag, ortagsfilters.waitblocks until a task reachesexited,killed, orfailed.stopcancels one task, or a batch of tasks.restartrestarts one task, or a batch of tasks.logsreads bounded task logs.eventsemits status/log event frames.
Example:
background-tasks start '{"id":"bg_demo","command":"sh","args":["-c","printf ready\\\\n; sleep 60"],"tags":["demo"]}'
background-tasks status '{"id":"bg_demo"}'
background-tasks logs --output auto '{"id":"bg_demo","lines":50}'
background-tasks stop '{"id":"bg_demo"}'Batch example:
background-tasks start --concurrency 2 '[
{"id":"bg_one","command":"sleep","args":["30"]},
{"id":"bg_two","command":"sleep","args":["30"]}
]'logs defaults to a bounded inline preview. When more log lines exist than the requested preview, --output auto returns a compact summary plus an artifact record pointing at the full log file.
{
"kind": "summary+artifact",
"summary": "Showing 50 of 412 log lines for bg_demo.",
"artifact": {
"key": "task.bg_demo.logs",
"kind": "text",
"absolute_path": "/abs/path/bg_demo.log",
"relative_path": "logs/bg_demo.log",
"size_bytes": 18320
}
}Use --stream with logs or events for NDJSON event frames, one JSON object per line.
Agents should prefer discovery commands over README scraping:
background-tasks doctor
background-tasks capabilities
background-tasks schema list
background-tasks schema show start
background-tasks examples list
background-tasks examples show startschema show returns JSON Schema generated from the same Effect Schema boundary used to decode payloads.
| Name | Required | Default | Description |
|---|---|---|---|
BACKGROUND_TASKS_HOME |
no | $HOME/.local/state/background-tasks |
Local state root for task metadata, logs, and artifacts. |
Task payloads may include environment variables for spawned commands. Treat those values as local secrets: do not commit payloads, logs, artifacts, or scan output containing credentials, private endpoints, customer data, or personal data.
bun install
bun run typecheck
bun test
bun run build
bun run smoke:npm-cli
bun run pack:dry-runThe full local verification command is:
bun run verifyPackage and release preparation details live in PUBLISHING.md.
GitHub Actions runs on pushes to main and on pull requests. The workflow installs with Bun, runs bun run verify, and inspects npm package contents with bun run pack:dry-run. Workflow permissions are read-only.
This project starts local processes and captures local logs by design. Review payloads before running them, and do not treat the CLI as a sandbox. The opencode control-plane session code is local coordination data, not a long-lived credential.
Please report security issues privately. See SECURITY.md.
Issues are welcome when they include enough context to reproduce or evaluate the request. See CONTRIBUTING.md and SUPPORT.md for project boundaries.
MIT. See LICENSE.