pi-human-inquire

pi-human-inquire turns plans, notes, specs, RFCs, recaps, research, diffs, and other structured content into reviewable documents where humans can ask agent questions and leave feedback directly inside the document.

It includes:

• direct Markdown review support for fast rendering without model-generated HTML
• the Reviewable Document skill (human-review), which opens Markdown directly when possible or creates a standalone review page when needed
• an in-browser review workspace for comments, contextual questions, threaded discussion, and submitting feedback back to Pi

Install

Pi packages can be installed from npm, git, or a local path.

Try without installing

pi -e npm:pi-human-inquire

Install globally

From npm:

pi install npm:pi-human-inquire

From git:

pi install git:github.com/alpeshvas/pi-human-inquire

From a local checkout:

pi install .

Install for a project

From npm:

pi install -l npm:pi-human-inquire

From git:

pi install -l git:github.com/alpeshvas/pi-human-inquire

From a local checkout:

pi install -l .

Run from source

Pi loads TypeScript extensions directly, so there is no build step. To inspect and run the package from source:

git clone https://github.com/alpeshvas/pi-human-inquire.git
cd pi-human-inquire
pi -e .

To install the local checkout globally:

pi install .

Or for just the current project:

pi install -l .

You can also preview the npm package contents before publishing or installing:

npm pack --dry-run

Usage

Generate or open a reviewable document

Use the skill:

/skill:human-review

You can invoke it with no arguments, with a file path, or with an instruction:

/skill:human-review notes.md
/skill:human-review turn this RFC into review HTML
/skill:human-review make the previous plan reviewable

The skill uses the provided content, or the most recent structured content in the conversation. Markdown paths are opened directly through the fast built-in renderer; other inline content can still be written as a review artifact and opened in the browser. If it cannot find suitable content, it asks you for a path or content.

Open existing Markdown or HTML

If you already have a Markdown or HTML file:

/annotate-html /absolute/path/to/document.md
/annotate-markdown /absolute/path/to/document.md
/annotate-html /absolute/path/to/document.html

Legacy alias:

/annotate-plan-html /absolute/path/to/document.html

In-browser review workspace

In the opened review workspace, you can:

• select text for comments
• continue threaded agent Q&A in place
• add document-level notes
• edit or remove comments
• submit feedback back into the active Pi session

Agent answers use the document, current block, selected text, existing comments, thread history, and recent session context.

Architecture

flowchart TD
  P["Pi package<br/>package.json"] --> S["Skill<br/>/skill:human-review"]
  P --> E["Extension<br/>commands + tool"]

  S --> H["Reviewable HTML or Markdown"]
  S --> T["open_html_review"]
  E --> T
  E --> C["/annotate-html or /annotate-markdown"]

  T --> B["In-browser review workspace"]
  C --> B

  B --> BR["ctx.sessionManager.getBranch<br/>recent session context"]
  BR --> M["Active Pi model<br/>for threaded agent Q and A"]
  M --> B

  B --> F["pi.sendUserMessage<br/>deliverAs: followUp"]
  F --> PI["Active Pi session"]

Loading

Skill options

Use direct Markdown paths for fastest rendering:

/skill:human-review notes.md
/annotate-markdown notes.md

Use lite mode for quick/minimal HTML output when HTML generation is still needed:

/skill:human-review --lite notes.md

Use stubs when iterating on a plan or spec and you want sections to remain stable across revisions:

/skill:human-review --with-stubs spec.md

By default, generated HTML artifacts are written to:

~/.agent/diagrams/<slug>.html

Feedback submission

Submitted feedback is saved locally and sent back into the active Pi session.

Compatibility notes

For now, /annotate-plan-html remains an alias for /annotate-html; /annotate-html also accepts Markdown.