convergent

Convergent is a Pi extension for aligning with the agent through a shared Markdown artifact before implementation happens. Instead of asking the agent to just implement, you ask it to externalize its mental model — a plan, a spec, or a design — in Markdown. You review and annotate the artifact, the agent revises it, and you iterate until you both agree on what it says before moving forward.

Why this matters:

• Terminal chat is hard to review. Dense plans need to be scrolled through, it's awkward to refer specifically to things, and feedback gets mixed into the conversation. Convergent gives you a stable, readable, annotatable, versioned artifact.
• Approval should be explicit. Instead of treating partial feedback as permission to continue, Convergent keeps revising the artifact until you approve the current revision.
• Only the approved version should shape implementation. Superseded revisions created via the back-and-forth process of alignment that leave behind outdated ideas and objections stay out of the main session, so the agent implements only from the artifact you approved.

Installation

Install from npm:

pi install npm:convergent

Or try without installing it:

pi -e npm:convergent

Starting a review

Review the last assistant message or an existing file:

/align [path/to/file.md]

Without a path, reviews the latest assistant message. With a path, reviews that file. The localhost review loop lets you annotate, request revisions, and approve; approved file reviews are written back to disk.

Convergent will also surface a review candidates automatically when the agent writes or edits Markdown, or finishes a substantial Markdown reply at which point you can simply press Ctrl+Shift+R to review it.

The review loop

1. Start a review using a method outlined above.
2. Add annotations in the browser UI. You can ask questions while annotating.
3. Submit a Revision Request, an isolated side session generates the next revision from the current revision and your annotations.
4. Repeat until aligned, then approve. The approved revision is handed to the main session as the replacement for what was reviewed.

Workflow gates

Convergent can turn any agent-generated Markdown into a human approval gate for an agent workflow. Use this when a prompt, skill, or other instruction has phases that should not proceed until the human reviewer agrees to a written review candidate: facts, specs, migration plans, API contracts, implementation plans, or other shared decisions.

When authoring agent workflows

Use this pattern for prompts, skills, or workflow instructions that include human-review gates.

For each human review gate, specify:

• the Markdown review candidate the agent must produce;
• the exact /align <review-candidate> command that opens it as an artifact;
• that the agent must stop until Convergent approval;
• that Revision Requests keep the same artifact open while Convergent creates new revisions from annotations;
• that the approved revision becomes authoritative for the next phase;
• what the agent should say if asked to continue early, for example: “I am waiting for Convergent approval of <review-candidate> before continuing.”

To apply this, paste the following into the agent that is authoring the workflow:

Read https://github.com/lostinpatterns/convergent#workflow-gates. Update the workflow I describe next so each human review gate uses Convergent: name the Markdown review candidate, include the `/align` command, require the agent to stop until approval, keep waiting on the same artifact through Revision Requests, resume only after the approved artifact reaches the main session, and include the early-continue response.

Features

• Main session context management — keep the review loop/process out of the main session: Ask uses temporary side sessions, revision generation happens outside the main conversation, intermediate annotations and superseded revisions stay out of context, and approval adds only the approved revision back as the replacement for the reviewed content.
• Ask — investigate the current revision in a private, fresh agent session before annotating. Ask sees the Markdown, draft annotations, and read-only codebase context, supports any Pi-accessible model, and does not affect the main session.
• Inline and global annotations — annotate a selected range or the whole revision; inline annotations anchor to exact positions in the raw Markdown.
• Structured annotations — selected ranges and global annotations compile into precise revision requests with raw Markdown anchors, offsets, line numbers, selected quotes, and marked surrounding excerpts, so the agent knows exactly what every annotation points at.
• Rendered and source views — review and annotate Markdown as rendered HTML or the raw source.
• Revision history — browse every saved revision to see how the agent addressed your feedback.
• Polished, keyboard-first workflow — low-friction, fast reviews that use shortcuts - press ? for the shortcut list.
• Light and dark themes.

Development

pnpm dev     # review UI against fixture Markdown, no Pi session needed
pnpm check   # typecheck

License

MIT.