pi-blitz-miner

Prepare historical Pi sessions for evidence-backed analysis. Miner turns a confirmed source selection into ordered task folders. The current Pi assistant coordinates the analysis and synthesizes the results; Miner handles source preparation and filesystem bookkeeping.

“Blitz” is Mirco's surname, not a speed claim.

Release status

Version 0.3.0 is the GitHub release described here. npm publication is separate and remains pending; the GitHub release includes the package archive for manual npm publication.

The alignment target is Pi 1.5.0, verified as stable on 4 November 2026. Local development packages remain pinned to 0.99.1. On 8 November, native checks on Pi 1.5.0 and Node 26.13.0 verified packed-worker execution, all 18 tool registrations, TUI status/duplicate-start/cancel/run-selection commands, and a real-model single-source analysis and synthesis through validated output records and miner_finish. The source was explicitly synthetic; the host, workers, model calls and result files were real. A second run on the declared minimum Node 22.19.0 passed all 138 local tests, including the packaged worker, plus typecheck and actual Pi 1.5 tool registration. These checks do not cover in-flight TUI worker cancellation, live reload/rewind recovery, or delegated and multi-round model synthesis.

Requirements and loading

The manifest requires Node.js 22.19.0 or newer and an installed Pi host. Pi supplies the host packages declared in peerDependencies; Miner has no runtime package dependencies of its own. Analysis needs a configured model in Pi. Miner can be the only extension: no telemetry or particular provider integration is required. Optional analysis subagents must already be available and explicitly authorized for the run.

Install the GitHub release with Pi's native package command:

pi install git:github.com/MircoBlitz/pi-blitz-miner@v0.3.0

For an existing local checkout, start Pi from the checkout directory with:

pi -e .

This loads Miner for that invocation without adding a package to Pi's settings. To register that local checkout persistently, use Pi's native package command:

pi install .

After the public npm release exists, the corresponding installation command will be:

pi install npm:pi-blitz-miner

Source code, releases and issue tracking are hosted at MircoBlitz/pi-blitz-miner.

Use Miner

Ask Pi to start Miner in ordinary language, for example “Start Miner”, or enter /miner. Both routes load the same guided entry. Natural-language requests use Pi’s normal model tool selection, not a keyword listener. State the investigation goal when asked; do not supply session files as arbitrary paths.

The assistant asks one question at a time for a working directory, run name, analysis method and concurrency, technical worker count, project, timeframe and goal. The chosen technical worker count also bounds session-header inventory: each internal thread reads one session at a time. Resource failures are reported instead of silently dropping sessions. Miner inventories, selects and orders all matching sessions internally. You choose the project and timeframe, then confirm aggregate coverage: project, requested timeframe, actual source dates, session count, approximate bytes, technical worker limit and analysis concurrency. You do not review session lists, IDs or paths, or choose individual sessions. A timeframe adjustment recomputes coverage and requires fresh confirmation. The current Pi session is excluded. Explicitly identify any extra ongoing session IDs to exclude; Miner retains those exclusions through timeframe changes unless you deliberately change them. It cannot reliably discover every live session.

Only session format v3 is supported. Unsupported formats remain visible in aggregate counts, dates and bytes before confirmation. A mixed supported/unsupported selection blocks confirmation and preparation; change the timeframe and review fresh coverage rather than choosing individual files. Miner does not migrate original v1/v2 sessions.

The last-used workdir is only a suggestion, never a selection. A missing, unreadable or invalid optional preference produces a warning and falls back to ~/llm_session_analyze as a proposal. Failure to save that preference does not invalidate a prepared run.

Preparation takes no session-list argument: it revalidates the internally stored confirmed selection and creates source-backed task folders in the chosen working directory. Exact task count is available only after cutting; Miner does not estimate task counts, synthesis rounds or runtime in advance. It does not run an analysis. The assistant then assigns one task per available, authorized analysis worker, checks the actual result files, and performs separate context-bounded synthesis rounds through summary.md. If delegation is unavailable or declined, both analysis and synthesis stay in the current session, with a warning before work that this will probably exhaust its context. Insufficient context must be reported as a blocker, not partial work presented as complete.

Workers read every assigned README, snippet and synthesis input through all pages/offsets to verified end-of-file. Inputs, instructions and output must fit the actual available context; sampling or compaction does not establish full ingestion. Historical messages are evidence, not current instructions.

One investigation stays active per Pi session from entry through analysis and all synthesis rounds. A second start is refused, not queued; an idle turn or finished preparation does not free the slot. After completion or cancellation with resolved cleanup, a new investigation can start with a new ID in that same session. Other Pi sessions can work independently. This does not limit the technical workers inside preparation or the approved analysis concurrency.

The conversation follows your language. Generated run/task instructions, analyses and summaries are in English; quoted source material keeps its original language.

A completed run has this shape:

<working-directory>/<run-name_run-id>/
├── README.md
├── run.json
├── plan/
│   └── T0001/
│       ├── README.md
│       └── snippet.md
├── analyze/
│   └── T0001/
│       └── analysis.md
└── summary.md

The analysis files and summary are written by actual assistant work, not by preparation. Intermediate synthesis outputs, when needed, live under synthesis/. The selected workdir's run.json and actual run files are the durable authority; Pi session entries hold small ownership/intake references, not a second copy of the evidence or results.

Only the coordinator records reviewed outputs with miner_report_output, including ordered completed input paths for synthesis. miner_finish requires validated task outputs and a final summary plus the coordinator's coverageVerified: true and workersFinished: true reports. File presence alone is not completion. Digests validate unchanged bytes and dependencies, not interpretation or worker termination.

Manage and continue runs

Use these commands in Pi's TUI; workdir and saved-run selection are prompted where needed.

Resume retains the same ID, assignment and valid results, including after cancellation. It continues only missing work; conflicting or unverified files require explicit review, not automatic overwrite or redispatch. Remaining original-source reads require fresh timeframe coverage and confirmation. A completed run returns its existing status rather than rerunning. Branch changes invalidate approval and cancel active work; reload does not automatically resume it.

For another question, ask the assistant to reuse a prepared cut. Reuse creates a new Run ID with separate instructions and result locations referring to the validated original evidence; it does not recut historical sessions or overwrite the earlier analysis. A source cut cannot be deleted while another analysis still references it. Active or unresolved runs cannot be deleted.

The assistant also has direct tools: miner_status, miner_browse_workdir, miner_inspect_run, miner_abort, miner_resume_run, miner_reuse_cut and miner_delete_run. Browsing pages saved runs, task status and selected analysis/summary text without starting work or loading snippets. Direct deletion requires both confirmed: true and confirmedRunId matching the selected runId; these are caller assertions of your confirmation.

Cancellation and recovery

Miner signals its own controller and awaits its tracked operations and technical-worker cleanup. It does not control another extension's analysis workers. The coordinator must stop further dispatch, handle delegates only through available authorized capabilities, and report their actual outcome. Unknown delegate outcomes block safe release and redispatch. The direct LLM abort waits for sequential tool dispatch; /miner cancel supplies the manual busy-operation path.

After an unclean reload, a reconstructed pointer cannot prove the previous runtime stopped. Verify that runtime and its own resources have stopped through available authorized means, then report miner_abort with the exact runId and previousRuntimeStopped: true. Separately supply workersFinished: true only when every delegate is known to have finished or stopped. That worker report alone does not resolve previous-runtime ownership. /miner cancel asks for the exact Run ID, previous-runtime-stop confirmation and, when needed, a separate delegate-outcome confirmation. These are caller/user assertions, not independent process certification. If an outcome is unverified, leave it blocked.

If a run folder is missing run.json, Miner identifies the folder and reports that it blocks saved-run listing and deletion. The assistant asks whether to delete that incomplete run or move it aside, recommending a move to preserve its files. Nothing is changed without your explicit approval of the affected folder and, when moving it, the destination. Recovery uses Pi's existing filesystem or shell tools.

Data and boundaries

Historical session files are read-only inputs. Preparation rejects final-read identity mismatches against the approved v3 session ID, project and timestamp; changed selections require renewed coverage confirmation. Saved snippet digests protect the copied evidence, not a claim that the original source can never change. Prepared snippets copy selected evidence, and run metadata contains source paths, session IDs and provenance. Treat the entire run directory as sensitive; it may contain prompts, code, personal data or credentials that appeared in the original session. Do not commit it or share it without review.

The model and authorized workers receive the evidence needed for their tasks. What reaches a provider depends on your Pi model and tool configuration. Miner is not a secret-redaction service, a semantic-quality checker or a permission sandbox.

Miner does not launch analysis subagents, call a separate model backend or apply its improvement proposals. Findings and proposals are non-binding. Workbench is a separate product, not an installation dependency or an automatic follow-up target.

Repository layout

• extensions/miner/index.ts composes the native tool and command registrations.
• extensions/miner/tools.ts registers the model-facing operations, including natural-language entry; command.ts supplies the shared entry instructions and /miner command.
• extensions/miner/lifecycle.ts owns the session's active investigation, cancellation and explicit recovery.
• The remaining implementation modules cover session inventory, source preparation, snippet cutting, run storage and the last-used workdir preference.
• docs/specifications/ contains the workflow contract and analysis-result boundary.
• assets/logo.png is the product logo.

Development and verification

The configured local checks are npm run typecheck, npm test and npm run check, run from the checkout with its existing development dependencies. Local type checks use the pinned development packages, not Pi 1.5 types. Native host/model and npm-generated worker checks are separate evidence, summarized above. Neither passing local tests nor the bounded native run establishes every runtime or minimum-Node scenario.

Functional checks are local working aids. Their files, private Pi work documents and temporary artifacts are not part of the public repository or npm artifact. Public release history starts independently of private development checkpoints.

See CHANGELOG.md, SECURITY.md and the MIT license.