🔧
   /|\
  / | \
 /  |  \
/___🤖__\

pi-tools

Power tools for pi. Clone repos and tear them apart. Run autonomous background loops. Lease secrets safely. Quit when you want to quit.

Install

# install dependencies
curl -sL https://raw.githubusercontent.com/joelhooks/pi-tools/main/setup.sh | bash

# install extensions
pi install git:github.com/joelhooks/pi-tools
pi config  # enable/disable individual extensions

Extensions

The herdr turn-ping extension and wait CLI now live in joelhooks/herdr-pings.

repo-autopsy

Repo analysis tools clone into ~/.repo-autopsy for cacheable inspection.

Tools: repo_clone, repo_structure, repo_search, repo_deps, repo_file, repo_find

This repo keeps the current Pi source mirrored at .agent_sources/github.com/earendil-works/pi-mono for SDK receipts.

linear-tracker

Project-local issue tracker resolver for agents that want to publish PRDs/issues. Linear is only allowed when local policy says Linear, a team association exists, and auth is available. Global MCP/auth is capability, not routing.

Tools:

• linear_tracker_resolve — reads nearest project policy and returns linear_direct, linear_mcp, payload_only, not_linear, or unknown
• linear_tracker_create_issue — creates one Linear issue via direct API auth and verifies readback
• linear_tracker_create_issues — creates dependency-ordered issue batches and verifies each created issue
• linear_tracker_get_issue — fetches an issue for readback verification

Policy lives in AGENTS.md, CLAUDE.md, docs/agents/issue-tracker.md, or .pi/settings.json.

session-reader

session-reader separates semantic recall from raw evidence. flowing_recall returns the canonical reflection, observation, and curated-page lanes. Native adapters then read bounded Pi, Claude, Codex, Cursor, Grok, and OpenCode sessions only when exact transcript evidence is needed. joelclaw owns flowing recall; native transcript stores remain immutable evidence.

Use /skill:session-search for the operating workflow.

Primary Pi tools:

• flowing_recall — explicit project/workstream recall with three separate lanes
• session_search — compatibility-only search for explicit native evidence, never semantic recall
• session_capture_status — verify native adapters and Pi/Claude/Codex delivery state
• session_context — bounded extraction for a session id or transcript path
• session_inspect — deterministic line inspection around a regex
• session_chunks — compact chunk search with safety caps

The read-only surface is available through MCP. Executor is the preferred catalog and Code Mode owner. Pi calls one executor_execute tool. Executor starts with recall. If recall reports No projection head, it calls discover_scopes and retries recall with one returned exact pair instead of guessing or searching transcripts. Native evidence search requires the signed receipt from a successful recall.

pi-session-recall-mcp-http serves Streamable HTTP for Executor. It:

• binds only to 127.0.0.1;
• requires a bearer token of at least 32 bytes;
• returns no query or body data from /healthz;
• creates a stateless MCP transport for each request;
• exposes only read-only, idempotent tools.

SESSION_RECALL_MCP_TOKEN="$(secrets lease session_recall_mcp_bearer_token --ttl 1h)" \
  pi-session-recall-mcp-http

After adding session_recall_mcp_bearer_token to agent-secrets, install the user LaunchAgent from a clean release:

session-reader/install-executor-memory-service.sh install /absolute/path/to/clean/pi-tools-release
curl --fail --silent http://127.0.0.1:4792/healthz

Register http://127.0.0.1:4792/mcp as a remote Streamable HTTP integration in Executor. Use Executor's credential handoff for the Authorization: Bearer value. Never put the token in a prompt, shell argv, source file, shared MCP config, or Executor integration metadata.

Root-owned scope discovery release

Production scope discovery trusts only this exact parallel release:

/Library/Application Support/JoelClaw/flowing-memory/releases/20260827-05d92ead-scope-v1

The adapter fails before credential lease until that hierarchy exists with uid 0, immutable 0555 directories, a 0444 manifest, and a 0555 executable. It never falls back to the user-owned release under ~/.joelclaw.

After the release and this consumer have passed review, the root-copy operator can install the already-reviewed source release. Do not run this during build or review:

sudo session-reader/install-scope-discovery-release.sh \
  /absolute/path/to/reviewed/20260827-05d92ead-scope-v1

The installer leaves the user release in place, verifies the source and staged copy, and creates the root-owned release without changing the active flowing-memory host release. Its immutable inputs are:

• manifest SHA-256 a5d2a737c7dd558ff3e3566646b85d43c2ce5514dee17c4bb09405b79ffcb998, 349 bytes;
• source commit 05d92eadb5091113c5fc648e95ced36eb5fb8f39 from that pinned manifest;
• artifact SHA-256 62922264b9f27df3ad9c18c095dabf3dd55477859522739ee396b7de78b3b6cf, 74,988,002 bytes.

After installation, restart the user LaunchAgent and run the read-only scope-discovery canary. A failed hierarchy, owner, mode, size, source, or digest proof remains a hard scope-discovery-unavailable result.

pi-session-recall-mcp remains the stdio rollback path. Do not run both transports as active catalog owners.

MCP tools: recall, discover_scopes, drill_down_session_evidence, inspect_session, expand_session, session_context, drill_down_session_chunks, and memory_skill.

discover_scopes accepts optional bounded project_hint and workstream_hint, a limit from 1 through 50 (default 10), and a required non-empty unique allowed_privacy grant. It returns semantic scope metadata, not raw evidence, so it neither requires nor mints an evidence receipt. Hints and the typed query travel only over child stdin. The adapter executes only the consumer-pinned standalone under the root-owned immutable hierarchy, re-proves every managed directory plus exact manifest and artifact owner, type, mode, size, identity, source, and digest before credential lease and immediately before spawn, leases only flowing_memory_runtime_database_url through the canonical secrets CLI, rejects any producer stderr byte, and gives the child a minimal environment.

recall requires an exact persisted project/workstream scope and returns a process-bound evidence receipt. The two drill-down tools reject calls without a valid receipt, cap native scans at 200 files, and never act as initial memory search.

Still removed:

• background reader-agent spawning

The native reader stays local-only because the current joelclaw sessions CLI accepts query text only in argv. Do not route private search text through that contract. Flowing recall uses the typed stdin request boundary.

Pi session_chunks wrapper safety defaults:

• defaults to limit: 5, context_before: 0, context_after: 0
• caps requests at limit: 10 and context 2 unless allow_large_output: true
• returns compact markdown by default; raw JSON requires compact: false plus allow_large_output: true
• excludes current-session matches by default when Pi exposes the current session id/file; pass exclude_current: false to include them intentionally

Use direct joelclaw session chunks only when you really want the raw CLI behavior.

shortlink-qr

Create stage/demo shortlinks with QR assets and a local Brain resource entry.

shortlink_qr({
  slug: "cascadia-viv",
  url: "https://x.com/Vtrivedy10/status/2031408954517971368",
  title: "Viv harness engineering article",
  push: true,
  background: "transparent",
});

Outputs:

• friendly https://joel.dev/<slug> shortlink
• native 1500×1500 QR PNG and SVG under resources/qr/
• PNG copied to the macOS clipboard
• optional ShitRat commit to joelhooks/joel-dev-link-shortener
• .brain/resources/shortlinks.svx resource-list entry with a pi-notes/portless URL when available

Backgrounds: transparent (default), white, or black (white QR code on black).

Command shortcut:

/shortlink-qr cascadia-viv https://example.com

secrets

Lease credentials safely with TTLs. No env files committed, no plaintext on disk.

Use secrets_lease to get the slack_bot_token with a 30 minute TTL

Tools: secrets_lease, secrets_status, secrets_revoke, secrets_audit

Requires agent-secrets daemon running.

License

MIT