Customize Feedback

Add feedback templates under prompts in Plannotator’s config.json. Plan and document feedback use the plan and annotate sections. Code review uses the separate review section. The file is <data-directory>/config.json. The data directory is normally ~/.plannotator, but PLANNOTATOR_DATA_DIR or an absolute XDG_DATA_HOME can change it. Plannotator reads the file again when it generates the next supported feedback message, so you do not need to restart it.

Plan and document feedback

Use prompts.plan for an agent’s plan-review decision:

{
  "prompts": {
    "plan": {
      "denied": "Revise the plan, address every item below, then call {{toolName}} again.\n\n{{feedback}}",
      "approvedWithNotes": "The plan is approved with these implementation notes:\n\n{{feedback}}"
    }
  }
}

Keep {{feedback}} in a template that should return your annotations. If you remove it, the template still runs, but the exported annotations are omitted from the message.

Key	Used when	Available placeholders	Built-in behavior
`plan.denied`	You request changes to an agent plan	`{{toolName}}`, `{{planFileRule}}`, `{{feedback}}`	Requires the agent to revise every submitted item before resubmitting and preserves the plan title unless asked to change it.
`plan.approved`	You approve a plan without notes	`{{planFilePath}}`, `{{doneMsg}}`	Tells the agent to execute the approved plan. OpenCode uses a shorter built-in message.
`plan.approvedWithNotes`	You approve a plan and include notes	`{{planFilePath}}`, `{{doneMsg}}`, `{{feedback}}`, `{{proceedSuffix}}`	Returns the approval plus your implementation notes. `{{proceedSuffix}}` is populated only by the OpenCode flow when it should start implementation.
`plan.autoApproved`	A non-interactive flow approves automatically	None	Reports that the plan was auto-approved and tells the agent to continue.

Use prompts.annotate when a supported agent wrapper formats annotations on a file, folder, or assistant message:

{
  "prompts": {
    "annotate": {
      "fileFeedback": "{{fileHeader}} notes for {{filePath}}:\n\n{{feedback}}",
      "messageFeedback": "Revise your response using these notes:\n\n{{feedback}}",
      "approvedWithNotes": "Approved. Continue without revising the reviewed content solely because of these notes.\n\n{{contextBlock}}{{feedback}}"
    }
  }
}

Key	Used when	Available placeholders	Built-in behavior
`annotate.fileFeedback`	An agent wrapper returns file or folder annotations	`{{fileHeader}}`, `{{filePath}}`, `{{feedback}}`	Labels the result as Markdown annotations, identifies the file or folder, and asks the agent to address the feedback.
`annotate.messageFeedback`	An agent wrapper returns annotations on the latest assistant message	`{{feedback}}`	Labels the result as message annotations and asks the agent to address them.
`annotate.approved`	No verified current user path	None	Plannotator accepts this config key, but no current feature reads it.
`annotate.approvedWithNotes`	A supported agent wrapper returns approval with non-blocking notes	`{{feedback}}`, `{{context}}`, `{{contextBlock}}`	Reports approval, passes the notes, and tells the agent not to revise or reopen the reviewed content solely because of them.

The annotation transport determines whether Plannotator applies a template:

Transport	Template behavior	Approval behavior
OpenCode and Pi wrappers	Apply configurable feedback and approved-with-notes templates	No-notes approval does not use `annotate.approved`
Direct `plannotator annotate` and `plannotator annotate-last` commands	Return exported feedback without templates	Plain-text approval is fixed to `The user approved.`
Structured JSON	Returns structured decisions without templates	Can return approval notes as `feedback`
Hook-native output	Returns the hook-native block or pass contract	Cannot return approval notes

Code-review feedback

Use prompts.review for the result of plannotator review, including local changes, pull requests, and merge requests:

{
  "prompts": {
    "review": {
      "approved": "# Code Review\n\nNo changes requested. Continue with the agreed next step.",
      "denied": "\n\nValidate each submitted finding against the code and report your verdict before changing anything."
    }
  }
}

Key	Used when	Placeholders	Built-in behavior
`review.approved`	You approve a code review	None	Returns a Code Review heading and says that no changes were requested.
`review.denied`	You send code-review annotations	None	Appends instructions to validate only the submitted findings, report evidence and a verdict for each one, and discuss them before changing code.

A review.denied override replaces only the built-in suffix. It leaves the annotations unchanged. Plannotator adds the suffix only when the submitted review has annotations. These settings do not change the instructions used by Ask AI or by an AI review job launched inside code review. Those jobs use their own prompts and any enabled global Agent Skills.

Agent-specific overrides

Place an override under runtimes inside the relevant section:

{
  "prompts": {
    "plan": {
      "denied": "Revise the plan using this feedback:\n\n{{feedback}}",
      "runtimes": {
        "opencode": {
          "denied": "Update the plan, then call {{toolName}}:\n\n{{feedback}}"
        }
      }
    },
    "review": {
      "runtimes": {
        "codex": {
          "approved": "# Code Review\n\nNo changes requested."
        }
      }
    }
  }
}

Supported runtime names are claude-code, amp, droid, kiro-cli, opencode, copilot-cli, pi, codex, and gemini-cli. For any key, Plannotator chooses the first non-blank string in this order:

prompts.<section>.runtimes.<runtime>.<key>
prompts.<section>.<key>
A built-in value for that runtime, when one exists
The built-in general value

An empty or whitespace-only string is treated as unset. A misspelled or unavailable {{placeholder}} remains unchanged in the returned message. A missing or malformed config file falls back to built-in behavior; malformed JSON also writes a warning to standard error.

Placeholder values

Placeholder	Value at runtime
`{{feedback}}`	Your exported annotations or notes.
`{{toolName}}`	The agent action used to resubmit a plan, such as `ExitPlanMode`, `submit_plan`, `exit_plan_mode`, or `plannotator_submit_plan`.
`{{planFileRule}}`	A file-location instruction when the current plan flow supplies one; otherwise an empty string.
`{{planFilePath}}`	The current plan’s backing-file path when supplied by the agent flow.
`{{doneMsg}}`	Optional save-path or checklist text supplied by the agent flow.
`{{proceedSuffix}}`	Optional OpenCode text that tells the agent to start implementation; empty in other current flows.
`{{fileHeader}}`	`File` or `Folder`.
`{{filePath}}`	The annotated file or folder path.
`{{context}}`	A short description of the approved source when the wrapper supplies one.
`{{contextBlock}}`	`{{context}}` followed by two newlines, or an empty string.

Check your change

Add a short marker such as [custom-plan-feedback] to one template.
Run the matching supported flow. For example, request a plan change for plan.denied, send an annotated code review for review.denied, or annotate a file through OpenCode, Pi, or Amp for annotate.fileFeedback.
Make sure that the returned message contains the marker and the expanded placeholders.
Remove the marker after you identify the selected key and runtime.

If the marker does not appear, make sure that the configuration path, JSON syntax, runtime name, and selection order are correct. See Configuration and Environment variables for the data-directory setting. Last verified against Plannotator OSS v0.25.0 on July 27, 2026. Maintained by the Plannotator project.

Start

Plans and documents

Code review

Reference

Agents

Editors and notes

Troubleshooting

Related project

Plan and document feedback

Code-review feedback

Agent-specific overrides

Placeholder values

Check your change

​Plan and document feedback

​Code-review feedback

​Agent-specific overrides

​Placeholder values

​Check your change

Plan and document feedback

Code-review feedback

Agent-specific overrides

Placeholder values

Check your change