> ## 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.

# Customize Feedback

> Change the messages Plannotator returns after plan, document, and code-review decisions.

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.                                                 |

<Warning>
  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`.
</Warning>

## Code-review feedback

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

1. `prompts.<section>.runtimes.<runtime>.<key>`
2. `prompts.<section>.<key>`
3. A built-in value for that runtime, when one exists
4. 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

1. Add a short marker such as `[custom-plan-feedback]` to one template.
2. 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`.
3. Check the message returned to the agent or printed by `plannotator review` for the marker and the expanded placeholders.
4. 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](/open-source/reference/configuration) and [Environment variables](/open-source/reference/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.