pi-blitz-miner0.2.0

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.2.0 is the initial GitHub release. npm publication is pending.

Requirements and loading

Use 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. 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.2.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 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. You review the selected session metadata and coverage before full-source preparation. The current Pi session is excluded. Name any other ongoing session IDs you want excluded; Miner cannot reliably discover every live session.

Preparation creates source-backed task folders in the chosen working directory. It does not run an analysis. The assistant then assigns one task per authorized analysis worker, checks the actual result files, and performs separate context-bounded synthesis rounds until summary.md exists. If you decline subagents, analysis stays in the current session and may exhaust its available context.

Miner operations run one at a time per Pi session. Wait for preparation to finish, or explicitly abort it through Pi, before starting a fresh intake with a changed assignment. Other Pi sessions can work independently. This does not limit the technical workers inside a preparation or authorized analysis subagents in their own sessions.

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. File presence proves technical completeness only, not correct interpretation or finished workers.

Ask the assistant to find saved runs or reuse a prepared cut for another question. Reuse creates separate instructions and result locations that refer to the original evidence; it does not recut historical sessions or overwrite the earlier analysis. Deleting a run requires explicit confirmation of its exact Run ID. A source cut cannot be deleted while another analysis still references it.

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

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.