opensec-pi-subagents

OpenSec Subagents for Pi: specialized agents in separate sessions that inherit the parent's model and thinking level. Bun build, for Pi-Bolt.

Packages

Package details

extension

Install opensec-pi-subagents from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:opensec-pi-subagents
Package
opensec-pi-subagents
Version
0.20.0
Published
Oct 4, 2026
Downloads
373/mo · 104/wk
Author
kushalkhemka
License
Apache-2.0
Types
extension
Size
789 KB
Dependencies
0 dependencies · 3 peers
Pi manifest JSON
{
  "image": "https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png",
  "video": "https://github.com/tintinweb/pi-subagents/raw/master/media/demo.mp4",
  "extensions": [
    "./dist-bun/index.js"
  ]
}

Security note

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

README

opensec-pi-subagents is OpenSec's build of @tintinweb/pi-subagents for Pi-Bolt, Pi compiled ahead of time on Bun.

  • It adds parent model and thinking-level inheritance, cached agent discovery, and the fixes listed below.
  • It ships as a prebuilt bundle with no runtime dependencies.

Install

pi-bolt install npm:opensec-pi-subagents
  • The Pi-Bolt installer offers to install it for you.
  • After installing, restart Pi-Bolt or run /reload.
  • Update it with pi-bolt update --extensions, and remove it with pi-bolt remove npm:opensec-pi-subagents.

Requirements

  • Pi-Bolt 0.6 or later (Pi 1.0), or Pi 0.84 or later run by Bun 1.3 or later.
  • This build runs on Bun only. For Pi on Node, use @tintinweb/pi-subagents.
  • Install one subagents extension at a time. This package and @tintinweb/pi-subagents register the same tools. If two such extensions are loaded, the one Pi loads first stays active and the other disables itself with a warning.

Features

  • Background agents by default, with optional foreground runs, steering, result retrieval and session resume.
  • Built-in Explore and Plan agents for read-only work, a general-purpose agent, and custom agent definitions.
  • Parallel and staged workflows through SubagentWorkflow (agent(), parallel(), pipeline()).
  • An /agents view for live conversations, settings, workflows and scheduled jobs.
  • Optional nested delegation, persistent memory, skill preloading and Git worktree isolation.
  • Agents inherit the parent session's model and thinking level unless their definition or the call overrides them.

Usage

Ask Pi to delegate work, for example: "Use an Explore agent to find the authentication code, then report the relevant files." Pi calls the Agent tool:

Agent({ subagent_type: "Explore", prompt: "Find authentication code", description: "Find auth files" })

Tools

Tool What it does
Agent Starts an agent. A background run returns an ID and notifies the main session when it finishes; set run_in_background: false when the next step must wait for its result. Also accepts session-scoped cron, interval and one-shot schedules.
get_subagent_result Returns the full result of an agent.
steer_subagent Redirects a running agent.
SubagentWorkflow Runs repeatable multi-agent work (agent(), parallel(), pipeline()).

Commands

Command What it does
/agents Inspect and manage agents: live conversations, settings, workflows and scheduled jobs.
@<agent> <message> With agent mentions enabled, sends a message to that agent, for example @explore check the RPC path. A finished agent can be resumed.

Custom agents

Put agent definitions in .pi/agents/<name>.md in a project, or in the global Pi agents directory.

Configuration

Setting Default Meaning
Background concurrency (/agents → Settings) 10 How many background agents run at once.

Further reading: workflows, RPC events, and the example workflows.

Notes

  • Interval schedules must be at least 1m; intervals and relative delays are capped at 3650d.
  • Worktree isolation is optional. On completion, an isolated agent's changes are committed to its branch.
  • Review /agents → Settings before enabling delegation or isolation for agents that can write.

Security

Subagents run with your user account's privileges and the tools they are granted, like Pi itself.

Workflow scripts run with full host access. The VM they run in keeps them deterministic; it is not a sandbox. Run only scripts you trust.

See SECURITY.md for the security model and how to report a vulnerability.

How this build is packaged

The package holds two files and no runtime dependencies:

  • dist-bun/index.js is a small ESM entry that Pi loads.
  • dist-bun/core.cjs is the extension itself, as readable CommonJS that Bun loads natively.

Pi's loader never has to transpile the extension. It adds tens of milliseconds to a launch instead of hundreds, and avoids a transpile of several seconds on the first launch after an install. Tools, commands, settings and file locations are those of @tintinweb/pi-subagents.

Changes from upstream

Based on @tintinweb/pi-subagents 0.19:

  • Inheritance and caching:
    • Agents inherit the parent's model and thinking level.
    • Agent discovery and configuration are cached and revalidated by file metadata.
  • Schedules:
    • Schedules longer than about 24.8 days no longer fire every millisecond; long delays run on chained timers.
    • A fire is skipped while the job's previous agent is still running.
    • Validating a cron expression no longer leaves a timer running, so pi -p exits.
    • A corrupt schedule file is kept as <file>.corrupt instead of being overwritten.
    • A canceled session switch no longer stops the scheduler.
  • Worktrees:
    • Isolated agents no longer lose their work when the preservation commit or a git status fails. Their worktree is kept and its path reported.
    • Quitting waits up to 15 s for stopped worktree agents to save their changes.
  • Stopping agents:
    • A stop issued before an agent's session exists is honoured.
    • A foreground resume can be stopped.
    • get_subagent_result with wait: true waits while a worktree is being created.
  • Pi 1.0:
    • @agent mentions start the conversation clone again.
    • Transcripts no longer repeat the system prompt.
    • ext: tool narrowing is enforced on deferred tool-to-tool calls too.
  • Workflows:
    • Code in meta is rejected before it runs.
    • Caches and log() output are bounded.
    • Children of a finished run are stopped.
    • Script paths must be regular files.
    • Schema patterns with nested quantifiers are refused.
    • Errors name the script line.
  • Output: terminal control sequences in agent output, gate output and logs are stripped before rendering.

The full history is in CHANGELOG.md.

License

Copyright 2026 OpenSec. Licensed under the Apache License, Version 2.0.

Based on @tintinweb/pi-subagents by tintinweb (MIT). The bundle includes croner (MIT). Their notices are in NOTICE.