# uip agent review-history

> Record review grades over time in a project's local review-history file with `uip agent review-history add`.

`uip agent review-history` manages the review grades recorded in a project's local review-history file. It does not run [`uip agent review`](./uip-agent-review.md) itself — `add` only records a grade you already have (for example, from a prior `review` run, or a manual assessment) so grade trends can be tracked over time. The history keeps the newest entries only (oldest are dropped once the cap is reached), most recent first.

Local-only — no login required.

## Synopsis

```
uip agent review-history add <grade> [path] [--errors <count>] [--warnings <count>]
```

All invocations honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip agent review-history add

### Arguments

| Name | Required | Purpose |
|---|---|---|
| `<grade>` | yes | Letter grade to record (A to F). |
| `[path]` | no (default `.`) | Agent project directory. |

### Options

| Flag | Purpose |
|---|---|
| `--errors <count>` | Number of error findings to record alongside the grade. |
| `--warnings <count>` | Number of warning findings to record alongside the grade. |

An invalid grade fails with `AgentReviewHistoryAddInvalidGrade`, listing the allowed set. A non-existent project directory fails with `AgentReviewHistoryAddInvalidPath`. An existing history file that isn't a JSON array of review entries fails with `AgentReviewHistoryAddMalformedHistory`.

### Examples

```bash
# Record a review grade for a project at a specific path
uip agent review-history add B ./my-agent

# Record a grade with finding counts, for the current directory
uip agent review-history add C --errors 2 --warnings 5
```

### Data shape (--output json)

```json
{
  "Code": "AgentReviewHistoryAdd",
  "Data": {
    "ProjectDir": "./my-agent",
    "Grade": "B",
    "RunAt": "2026-09-02T10:00:00.000Z",
    "HistoryCount": 1
  }
}
```

`Errors` and `Warnings` are included only when the corresponding option was passed.

## Related

- [`uip agent review`](./uip-agent-review.md) — produces the grade this command records.

## See also

- [Global options](./global-options.md), [Exit codes](./exit-codes.md).