A managed Pi package that adds file search, self-hosted web research, focused user interaction, background processes, and T3-compatible subagent tools.
| Capability | Tools | Notes |
|---|---|---|
| File search | fd, rg |
Uses system binaries when available, with checksum-verified official fallbacks |
| Web research | search, scrape, crawl |
Requires an explicitly configured self-hosted Firecrawl endpoint |
| User interaction | ask_user |
Presents one focused question with selectable and custom-answer paths |
| Background processes | bg_start, bg_status, bg_list, bg_kill |
Runs non-interactive, session-scoped processes with bounded output |
| Workflows | subagent_workflow |
Standalone Pi, forwards to the separately installed subagents plugin |
The package supplements rather than replaces @tintinweb/pi-subagents.
The subagent compatibility layer supports @tintinweb/pi-subagents 0.22.0 and 0.23.0. In standalone Pi it exposes subagent, subagent_result, subagent_steer, and an upstream-enabled subagent_workflow, preserving Pi's permission hooks through public nested execution.
In T3 Code, a verified native delegation bridge takes precedence. Pi's private
83A2
-child tools are hidden and blocked, and the agent uses T3's delegate_task and task/thread controls instead. Those children have real, clickable T3 conversations. Pi agent definitions and workflow scripts are not silently translated. No T3 fork or dependency patch is needed. Set PI_TOOLING_SUBAGENTS_COMPAT=0 to disable this layer, including native-delegation preference.
It also bundles background-terminals and workflows skills so Pi receives operational guidance alongside the specialized tools they describe.
- Pi 1.1.0 or newer with managed Git-package support
- Node.js and npm available to Pi's package manager
- A self-hosted Firecrawl endpoint if the web-research tools will be used
Development dependencies pin the Pi host packages to 1.5.0. This baseline supports native llama.cpp decision models. Their router must be llama.cpp 0.6.0 or newer and advertise decisions in architecture.output_modalities. Pi host packages remain wildcard peers, as required for managed packages.
pi install git:github.com/jhs88/pi-toolingPi clones the repository and installs its production dependencies beside the extension. Do not copy the repository into ~/.pi/agent/extensions; auto-discovered source directories do not receive the same managed dependency lifecycle.
Update managed extensions only:
pi update --extensionsOr update Pi and all managed packages:
pi update --allSee docs/package-lifecycle.md for dependency reconciliation and repair instructions.
Use @tintinweb/pi-subagents@0.23.0 with Pi 1.1.0 or newer. Version 0.22.0 remains supported. Native MCP, codemode, tool search, project trust, and nested tool scoping are supplied by upstream. No source patch is needed. The development and RPC verification baseline is Pi 1.5.0.
Children with extensions enabled can start their own MCP servers. Use extensions: false, isolated: true, or exclude_extensions: builtin:mcp when they should not. Restricted MCP access uses explicit ext:builtin:mcp/<tool> selectors. The obsolete native MCP patch and command have been removed. Use explicit extension selectors for restricted agents; bare MCP tool names are not an authorization boundary.
Set the self-hosted endpoint in the process environment or in ~/.pi/agent/.env:
FIRECRAWL_API_URL=https://firecrawl.example.com
# Optional when the self-hosted service requires authentication:
FIRECRAWL_API_KEY=<optional-key>Configuration precedence is:
- process environment;
- Pi's
agent/.env.
Only explicit HTTP(S) endpoints are accepted. The public Firecrawl Cloud endpoint is never selected as a fallback.
- Standalone Pi workflow execution uses the upstream subagents plugin, including its scheduling, limits, progress UI, and same-session replay. Pi Tooling does not impose a separate three-child cap. T3 sessions use native delegation instead; Pi-specific workflows require standalone Pi.
- Background processes are non-interactive, session-owned, output-bounded, redacted, and terminated as process trees.
- Firecrawl output is bounded, persisted when oversized, and cancellable.
- Downloaded
fdandrgfallbacks use pinned checksums from official release assets.
npm ci
npm run verifyThe verification command runs TypeScript checks and the complete test suite. For packaging changes, also verify a production-only installation:
rm -rf node_modules
npm ci --omit=dev --ignore-scripts
test -f node_modules/@effect/platform-node/package.jsonRead CONTEXT.md and AGENTS.md before changing architecture or runtime behavior. Runtime state such as node_modules, downloaded binaries, workflow artifacts, and terminal logs is not committed.
The implementation is adapted from davis7dotsh/my-pi-setup@797eaf6. Component-specific adaptation notes are recorded in the PROVENANCE.md files and supporting historical research under docs/history/.
The pinned upstream snapshot had no detected license. The provenance records document that limitation and the scope of the adaptations.