Pi Tooling

A managed Pi package that adds file search, self-hosted web research, focused user interaction, background processes, and bounded workflow orchestration.

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	workflow, /workflows	Runs explicitly requested JavaScript workflows with bounded fan-out

The package supplements rather than replaces @tintinweb/pi-subagents.

The subagent compatibility layer exposes subagent, subagent_result, subagent_steer, and an upstream-enabled subagent_workflow by default on supported hosts. No environment switch is needed, including when T3 launches Pi. It requires the pinned subagents 0.19.0 package and Pi's public loadout and ctx.executeTool APIs. It preserves permissions and supplies foreground progress fields for T3 without editing either dependency. Set PI_TOOLING_SUBAGENTS_COMPAT=0 to disable it. The repository owner has confirmed subagent tool visibility in T3's UI.

It also bundles background-terminals and workflows skills so Pi receives operational guidance alongside the specialized tools they describe.

Requirements

• 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.1.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.

Install

pi install git:github.com/jhs88/pi-tooling

Pi 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

Update managed extensions only:

pi update --extensions

Or update Pi and all managed packages:

pi update --all

See docs/package-lifecycle.md for dependency reconciliation and repair instructions.

Subagent native MCP compatibility

Pi's CLI loads native MCP, but @tintinweb/pi-subagents 0.19.0 does not initialize it in SDK child sessions. This package provides an explicitly invoked compatibility patch, not a fork or an automatic install hook:

# From this development checkout:
npm run compat:subagents -- --check
npm run compat:subagents

The packaged command is pi-subagents-compat when this package's npm bin directory is on PATH. Pin the separate Pi package to npm:@tintinweb/pi-subagents@0.19.0. Reapply the patch after a reinstall or package reconciliation, then run /reload.

The command checks the Pi version and reviewed package/source hashes before writing, backs up changed files, and is safe to repeat. Unknown releases or source changes fail closed. See compat/README.md for tool selectors, isolated-session behavior, and updating or removing the patch.

Configure Firecrawl

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:

1. process environment;
2. Pi's agent/.env.

Only explicit HTTP(S) endpoints are accepted. The public Firecrawl Cloud endpoint is never selected as a fallback.

Safety defaults

• Workflow execution is explicit, limited to three children, and cannot recursively invoke orchestration tools.
• 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 fd and rg fallbacks use pinned checksums from official release assets.

Development

npm ci
npm run verify

The 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.json

Read 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.

Attribution

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.