pinotator

Clipboard-first transcript citations for Pi.

pinotator lets you copy text from the current Pi session, keep it as a small citation set, and send that citation context back to the model in a structured way.

Early preview: pinotator is usable today, but commands and package details may still evolve before 1.0.0.

See the changelog for release notes.

Features

• Auto-captures copied text from the current Pi session transcript.
• Supports manual clipboard capture when you want to cite arbitrary text.
• Keeps a numbered active citation set you can reference as [1], [2], or @p1, @p2.
• Sends citations back to the model in a structured pinotator_citation format so they do not collide with ordinary numbered lists.
• Matches common rendered Pi output, including markdown formatting, blockquotes, tables, edit diffs, and command blocks.
• Keeps citation history so you can review what was captured, sent, or cleared.
• Supports branch-aware source filtering with tree-sync.
• Supports one-turn or windowed send suppression with skip.
• Clears citations after send by default so the active set stays focused.

Install

Install globally for your Pi environment:

pi install npm:pinotator

Install project-locally:

pi install -l npm:pinotator

How it works

1. Copy text from the current Pi transcript.
2. pinotator matches that copied text back to the source message or tool output.
3. The citation appears in the Pinotator widget above the editor.
4. Ask your next question and refer to the captured citations by number.

Example flow:

copy a code block or rendered diff from the transcript
→ Pinotator captures it as [1]
→ ask: "Use [1] to explain the regression" 

If you want to capture clipboard text that did not come from the current transcript, use manual capture.

/pinotator command

/pinotator                         show current citations and status
/pinotator status                  show state summary
/pinotator help                    show help
/pinotator hide                    hide widget without clearing citations
/pinotator clear                   clear all active citations
/pinotator clear 2 4-6             remove citations by display ref/range
/pinotator remove 2 cit_x          remove citations by display ref or durable id
/pinotator add-clipboard           manually capture current clipboard with safety checks
/pinotator history 15              show recent citation history
/pinotator skip                    skip sending citations on the next turn
/pinotator skip begin              start a skip window
/pinotator skip end                end a skip window
/pinotator tree-sync on|off        keep only citations whose sources exist on the current branch
/pinotator clear-on-send on|off    clear active citations after they are sent (default on)

Compatibility aliases are accepted but intentionally omitted from autocomplete so the command list stays clean.

Keyboard shortcut

ctrl+alt+c   manually capture the current clipboard with safety checks

Manual capture and safety

/pinotator add-clipboard and ctrl+alt+c capture the current clipboard even when the text did not come from the current Pi transcript.

Manual capture is safety-gated:

• empty clipboard is rejected
• oversized clipboard content is rejected
• secret-like content is rejected by default

This is meant to reduce the chance of accidentally storing tokens, credentials, or large unrelated blobs as citations.

Citation behavior

When citations are sent to the model, pinotator wraps them in explicit pinotator_citation records with:

• display refs such as [1]
• aliases such as @p1
• durable citation ids
• origin (transcript or manual)
• source metadata when available

This makes Pi prompts like these much more reliable:

Summarize [1].
Compare [1] and [2].
Use @p3 as the evidence for the bug report.

Important behaviors

tree-sync

With tree-sync on (default), Pinotator removes active citations whose source messages are no longer on the current session branch.

This helps prevent “ghost citations” from abandoned or rewound branches.

clear-on-send

With clear-on-send on (default), active citations are removed after they are sent to the model.

That keeps the active set small and focused on the current turn.

skip

Use skip when you want to keep citations captured but not inject them into the next model turn.

• /pinotator skip — skip one turn
• /pinotator skip begin — start a skip window
• /pinotator skip end — end the skip window

What Pinotator is good at

Pinotator is especially useful when you want to cite:

• rendered edit diffs
• command output blocks
• tool results
• structured markdown output
• earlier assistant analysis or code snippets

It is designed for the practical Pi workflow of:

• copy something useful
• keep it as a citation
• ask a follow-up grounded in that exact text

Development

For local validation and extension load checks:

npm run validation
npm run quality