> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plannotator.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Answer Your Agent's Questions Asynchronously

> Answer your agent's questions asynchronously in Plannotator: question cards you fill in on your own time, a quality interface for terminal and desktop agents alike.

<Frame>
  <video className="block dark:hidden w-full" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-flow.mp4?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=f1d6321e68a408cdeb735b809643e403" autoPlay muted loop playsInline controls data-path="images/questions-flow.mp4" />

  <video className="hidden dark:block w-full" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-flow-dark.mp4?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=a23ff8e29b831e171f41027fba1a0b4c" autoPlay muted loop playsInline controls data-path="images/questions-flow-dark.mp4" />
</Frame>

Your agent has questions for you. Instead of asking them one at a time in a chat prompt, it writes them into its plan or document, and Plannotator shows each one as a card. You answer them all in one place, on your own time, and send them back together.

A modern model has no reason to sit blocked on a prompt. Terminal agents and desktop agent apps both lack a good interface for answering questions. Plannotator works with both.

The post [An interactive UI for the grill-me skill](https://plannotator.ai/blog/an-interactive-ui-for-the-grill-me-skill), written before question blocks existed, shows the same idea through `/plannotator-last` (a tool for annotating your agent's last message, useful for CLI agents).

## How to use

**With the skill.** The Plannotator installer adds a `plannotator` skill for Claude Code, Codex, and other agents that read `~/.agents/skills`. It teaches the agent the question syntax. Nothing to set up. Ask your agent to use it:

```text theme={null}
Use the plannotator skill. Write your questions for me as question blocks in a Markdown file, then open it with plannotator annotate.
```

**Without the skill.** Copy this prompt into your agent's `AGENTS.md`, `CLAUDE.md`, or a skill of your own:

````markdown expandable theme={null}
## Asking the reviewer questions

When a decision needs the reviewer (a trade-off you cannot settle from the code or the conversation), write it as a question block. The reviewer answers in place, and the answers come back to you in an "Answers to your questions" section at the top of their feedback, with the questions they left open listed under "Unanswered".

```markdown
:::question
Where should losing conflict versions be kept?

Last-write-wins silently drops the loser unless we keep it somewhere.

- [ ] Local only, purged after 30 days — cheap, no server change
- [ ] Server-side per user — survives reinstall, needs a retention policy
- [ ] Nowhere — accept silent loss for v1

Recommended: Local only, purged after 30 days
:::
```

- `:::question` picks one choice, `:::question-multi` picks any number, `:::question-text` asks for free text (a block with no choices is free text too).
- The first line is the question. Other prose lines are context.
- Choices are task-list items: `- [ ] label`, optionally `- [ ] label — why`. The reviewer can always answer "Other", add a note, or skip.
- `Recommended: <label>` marks your recommendation. Text that matches no choice is offered as a suggested answer.
- `- [x]` means the choice is already settled. Use it when you resubmit: keep an answered question with the chosen choice checked, or remove the block and write the decision into the prose.
- Leave blank lines between the parts so the block also reads well on GitHub.
- Ask only what you cannot decide alone, and keep a round short (about 8 questions at most). Do not ask rhetorical questions or questions the codebase answers.
- Each answer comes back under its question (`### Q2. <question> (line N)`) as `Answer: <choice>`, marked `(your recommendation)` when the reviewer took yours, or as `Other: …`, free text in a quote, or `Skipped`, plus any `Note:`. A question you marked `- [x]` is settled and only comes back if the reviewer changed it or added a note.
````

Then:

1. Your agent writes its questions into its plan or a Markdown file. Plannotator opens it.
2. You answer the cards.
3. You click **Send answers**. The agent gets every answer in one message.

See [Agent Skills](/open-source/start/skills) for what the installer sets up.

## Where it works

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.

From the next Plannotator release, the Pi integration keeps working during plan review while you answer. Claude Code follows.

## The three kinds of question

| Block | You answer with |
| - | - |
| `:::question` | One choice. |
| `:::question-multi` | Any number of choices. |
| `:::question-text` | Free text. A block with no choices is also free text. |

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-card-multi-choice.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=7cc93b7affeb70473c481f07c1c1fae8" alt="A multi-choice question card asking which endpoints get a stricter budget, with three endpoints checked." width="1468" height="596" data-path="images/questions-card-multi-choice.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-card-multi-choice-dark.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=5e4b7a283bf81fc73b246c3860b86b81" alt="A multi-choice question card asking which endpoints get a stricter budget, with three endpoints checked." width="1468" height="596" data-path="images/questions-card-multi-choice-dark.webp" />
</Frame>

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-card-free-text.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=677c25596447376c3194c41032bfc843" alt="A free-text question card asking what the 429 response body should tell the customer, with a typed answer." width="1468" height="442" data-path="images/questions-card-free-text.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-card-free-text-dark.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=73c40018a5a92ae07fd6f9fb4fe3c016" alt="A free-text question card asking what the 429 response body should tell the customer, with a typed answer." width="1468" height="442" data-path="images/questions-card-free-text-dark.webp" />
</Frame>

## What the agent writes

A question block starts with `:::question` and ends with `:::`.

```markdown theme={null}
:::question
Where should losing conflict versions be kept?

Last-write-wins silently drops the loser unless we keep it somewhere.

- [ ] Local only, purged after 30 days - cheap, no server change
- [ ] Server-side per user - survives reinstall, needs a retention policy
- [ ] Nowhere - accept silent loss for v1

Recommended: Local only, purged after 30 days
:::
```

* The first line is the question. Lines before the choices are context.
* Each choice is `- [ ] label`. A reason can follow the label after `-`.
* `Recommended:` names the agent's pick. If it matches no choice, Plannotator shows it as a suggested answer.
* `- [x]` marks a choice as already settled.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-card-single-choice.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=1a981d20b6f5cad0580934b56c495e32" alt="An open single-choice question card, Question 1 of 4, with three choices, a Recommended tag on one, an Other option, and Add note, Skip, and Accept recommended buttons." width="1468" height="696" data-path="images/questions-card-single-choice.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-card-single-choice-dark.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=2694206bac7e4e3f41da5ee2f40924eb" alt="An open single-choice question card, Question 1 of 4, with three choices, a Recommended tag on one, an Other option, and Add note, Skip, and Accept recommended buttons." width="1468" height="696" data-path="images/questions-card-single-choice-dark.webp" />
</Frame>

The optional Plannotator Flavored Markdown reminder includes a short paragraph and an example of question blocks. Turn it on with `"pfmReminder": true` in `~/.plannotator/config.json`. See [Configuration](/open-source/reference/configuration).

## How you answer

Each card shows "Question N of M" and a status: Open, Answered, Skipped, or Settled.

* Pick a choice, or type your own answer in **Other…**.
* **Add note** adds a comment to your answer.
* **Skip** tells the agent you chose not to answer.
* **Accept recommended** fills in the agent's pick. It shows only on an open question that has one.

You can also select and comment on the question text like any other text. See [Annotations and feedback](/open-source/workflows/annotations-and-feedback).

Click the answered count in the header to jump to the next open question.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-header-send-answers.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=8c5eaf1fc918d6da06ee8be65b91c3e8" width="391" alt="The plan review header showing 4/4 answered, a Send answers button, and Approve." data-path="images/questions-header-send-answers.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-header-send-answers-dark.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=a171a8981ea7cc09f9fc189a34b3f511" width="391" alt="The plan review header showing 4/4 answered, a Send answers button, and Approve." data-path="images/questions-header-send-answers-dark.webp" />
</Frame>

The annotations panel lists every question in a **Questions** section above your comments. Answers are saved in your draft, so they survive a reload, and `Mod+Z` undoes them.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-panel-answered.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=b7786ef4a0fdaaa656f795dc3bea188a" width="288" alt="The annotations panel with a Questions section at 4/4, each question listed with its answer, above an empty Comments section." data-path="images/questions-panel-answered.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-panel-answered-dark.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=f03004e246a1b2012bd826055dd09738" width="288" alt="The annotations panel with a Questions section at 4/4, each question listed with its answer, above an empty Comments section." data-path="images/questions-panel-answered-dark.webp" />
</Frame>

## What the agent gets back

Answers come first in the feedback. This is what an agent received after **Send answers** on a four-question plan:

```markdown theme={null}
## Answers to your questions

4 of 4 questions answered.

### Q1. Where should the limit be enforced? (line 25)
Answer: In the Node middleware after auth (your recommendation)

### Q2. Which algorithm should the counter use? (line 41)
Answer: Token bucket

### Q3. Which endpoints should get their own, stricter budget? (line 61)
Answer:
- `POST /v2/orders`
- `GET /v2/reports/export`
- `POST /v2/webhooks/test`

### Q4. What should the 429 response body tell the customer? (line 74)
Answer:
> You've hit the rate limit for this API key (600 requests/minute on the Team plan). Retry after the number of seconds in the Retry-After header. Need more headroom? Contact support with your key ID.
```

"(your recommendation)" means you accepted the agent's pick. A note comes back as `Note:`, a skipped question as `Skipped`, and questions you did not answer are listed under "Unanswered".

In Claude Code, the whole message looks like this:

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-agent-feedback-terminal.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=7d2ce458c1032b125e8c3f9fc670a09b" alt="A Claude Code terminal showing the Plannotator feedback after Send answers: instructions to revise the plan, then Answers to your questions with four answered questions." width="1600" height="1301" data-path="images/questions-agent-feedback-terminal.webp" />

  <img className="hidden dark:block" src="https://mintcdn.com/plannotator/P_Mwm6tav4UNIqRn/images/questions-agent-feedback-terminal-dark.webp?fit=max&auto=format&n=P_Mwm6tav4UNIqRn&q=85&s=3ca2bbc0ef456919261acc4300611a08" alt="A Claude Code terminal showing the Plannotator feedback after Send answers: instructions to revise the plan, then Answers to your questions with four answered questions." width="1600" height="1301" data-path="images/questions-agent-feedback-terminal-dark.webp" />
</Frame>

## Send answers in plan review

When your only feedback on a plan is answers, the main button reads **Send answers**. The agent is told you answered its questions and is asked to revise the plan and resubmit. It does not get the "your plan was not approved" message.

If you also comment or edit the plan, the button reads **Send feedback**, and the answers go at the top of the normal feedback.

To change the message the agent receives after **Send answers**, set the `answered` key in `prompts.plan`. See [Customize Feedback](/open-source/reference/custom-feedback#plan-and-document-feedback).

<Warning>
  In Claude Code, **Approve** does not send answers or notes to the agent. Plannotator warns you first. To send answers, use **Send answers**.
</Warning>

## Resubmitting with `- [x]`

On resubmit, the agent does one of two things with each answered question:

* It removes the block and writes the decision into the plan.
* It keeps the block and marks the chosen choice `- [x]`.

A settled choice shows as selected with a "Settled" tag. You can still change it. A settled question comes back to the agent only if you changed it or added a note.

## Limits

* Share links carry an answer as a comment on the question, not as a filled-in card.
* A browser agent using Plannotator's WebMCP tools can read questions and answers but cannot answer.
* If the agent rewords a question, your earlier answer is no longer attached to it. The answer shows in the Questions section as unanchored and is still sent.

Last verified on October 3, 2026, using Plannotator release v0.27.25, product commit `c9c8cbbb`. Screenshots and the clip were captured from v0.27.23. Maintained by the Plannotator project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.