What does the agent receive back after I answer?

Answers come first in the feedback under 'Answers to your questions', one per question with line references. Accepted recommendations are marked '(your recommendation)', notes come back as Note:, skipped questions as Skipped, and unanswered questions are listed under 'Unanswered'.

Where do questions work?

Questions work in plan review, in plannotator annotate on a Markdown file or folder, and in plannotator last. They do not work on HTML pages, live apps, diagram files, or in code review.

Is Plannotator open source?

Yes, it is listed under the Open Source section of its documentation and is maintained by the Plannotator project.

Plannotator — Answer your AI agent's questions asynchronously in one UI

Plannotator is an open-source tool that lets AI coding agents ask you questions asynchronously. Instead of blocking on chat prompts one at a time, the agent writes its questions as structured question blocks (:::question, :::question-multi, :::question-text) inside a Markdown plan or document. Plannotator renders each question as a card you can answer at your own pace, then sends all answers back to the agent in a single structured message. It works with terminal agents (like Claude Code and Codex) and desktop agent apps alike.

Key Features

Structured question blocks in Markdown

Agents embed questions directly in plans or documents using :::question (single choice), :::question-multi (multiple choices), and :::question-text (free text) blocks with task-list style choices, context lines, and a Recommended pick.

Question cards you answer on your own time

Each question appears as a card with a status (Open, Answered, Skipped, or Settled), a question counter, options to add a note, skip, type a custom answer via 'Other…', or accept the agent's recommendation with one click.

Agent skill installer

The installer adds a plannotator skill for Claude Code, Codex, and any agent that reads ~/.agents/skills, teaching the agent the question syntax with no setup required.

Structured answers returned to the agent

Clicking Send answers delivers every response in one message under 'Answers to your questions', with per-question answers, notes, skipped items, unanswered questions, and '(your recommendation)' markers.

Images in questions

A question can embed a mockup or screenshot via a Markdown image (local path or URL), displayed on the card under the question text.

Settled questions on resubmission

When an agent resubmits, answered questions are either written into the prose or kept as blocks with the chosen choice marked - [x]; settled questions only return to the agent if changed or annotated.

Draft persistence and undo

Answers are saved in your draft so they survive a reload, and Mod+Z undoes them; clicking the answered count in the header jumps to the next open question.

Multiple workflow surfaces

Questions work in plan review, in plannotator annotate on Markdown files or folders, and in plannotator last; a Plannotator Flavored Markdown reminder can be enabled in the config to teach agents question syntax.

How It Works

1. Agent writes question blocks

You ask the agent to use the plannotator skill (or copy the provided prompt into AGENTS.md, CLAUDE.md, or your own skill). The agent writes its questions as :::question blocks in its plan or a Markdown file.

2. Plannotator opens the file

Plannotator opens the plan or document (via plannotator annotate, plannotator last, or plan review) and renders each question block as an answerable card.

3. You answer the cards

Pick a choice, type a custom answer, add a note, accept the recommended pick, or skip — on your own schedule, all in one place.

4. Answers go back in one message

Click Send answers (or Send feedback if you also commented or edited the plan) and the agent receives every answer, note, and skipped question in a single structured message.

Pros & Cons

Pros

Works with both terminal agents and desktop agent apps, filling a real gap in how agents ask questions
No setup needed when using the bundled skill for Claude Code, Codex, and agents reading ~/.agents/skills
Open source
Flexible answer types: single choice, multi choice, free text, custom 'Other' answers, notes, and skip
Answers persist in drafts across reloads, with undo support
Structured feedback format keeps answers, notes, and unanswered questions clearly separated for the agent

Who It's For

Best for

Developers using Claude Code, Codex, or similar terminal/desktop coding agents who want a better interface than chat prompts for agent quest
Teams practicing plan review workflows where agents need stakeholder input on trade-offs
Users who want to answer agent questions asynchronously rather than being blocked in conversation

Not ideal for

Reviewing questions on HTML pages, live apps, or diagram files — question blocks are unsupported there
Browser-based agents that need to answer questions autonomously (they can only read them via WebMCP)
Developers wanting their agent to make all decisions without human input — the tool exists specifically to route decisions to a reviewer

Use Cases

Resolving trade-off decisions during AI-driven plan review without a blocking chat back-and-forth

Letting terminal agents like Claude Code or Codex ask clarifying questions with a proper UI

Batch-answering an agent's questions asynchronously while working on other tasks

Reviewing design mockups embedded in question cards before approving an approach

Tracking which questions are settled versus still open across plan resubmissions

FAQ

What does Plannotator do for agent questions?

Instead of an agent blocking on chat prompts one at a time, it writes questions into its plan or document as question blocks, and Plannotator shows each one as a card. You answer them all in one place, on your own time, and send them back together in a single message.

Which agents does Plannotator work with?

The installer adds a plannotator skill for Claude Code, Codex, and other agents that read ~/.agents/skills. Without the skill, you can copy the provided prompt into your agent's AGENTS.md, CLAUDE.md, or a skill of your own. Plannotator works with both terminal agents and desktop agent apps.

What types of questions are supported?

Three kinds: :::question for picking one choice, :::question-multi for any number of choices, and :::question-text for free text (a block with no choices is also free text). Choices are task-list items with optional reasons, and the agent can mark a recommendation or pre-settle a choice with - [x].

Can questions include images?

Plannotator