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 default file is ~/.plannotator/config.json. If PLANNOTATOR_DATA_DIR is set, use <PLANNOTATOR_DATA_DIR>/config.json instead. 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}}"
    }
  }
}

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.

OpenCode, Pi, and Amp wrappers apply the configurable annotate templates. Direct plannotator annotate and plannotator annotate-last commands return exported feedback without applying those templates. Direct approval text is fixed to The user approved.. The --json and --hook options use structured output. No current feature reads annotate.approved.

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.

Verify 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.
Check the message returned to the agent or printed by plannotator review for the marker and the expanded placeholders.
Remove the marker after confirming the correct key and runtime were selected.

If the marker does not appear, confirm the config path, JSON syntax, runtime name, and selection order. See Configuration and Environment variables for the data-directory setting. Last verified against Plannotator OSS v0.23.1 and source commit da5e0102 on July 18, 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

Verify your change

​Plan and document feedback

​Code-review feedback

​Agent-specific overrides

​Placeholder values

​Verify your change

Plan and document feedback

Code-review feedback

Agent-specific overrides

Placeholder values

Verify your change