# Diagnostics Check List

`agents diagnostics` runs the checks listed below.  Each check returns one
of three statuses: **ok**, **warn**, or **error**.  When the `--check` flag
is passed the command exits with code 1 if any check reports `error`.

---

## Checks

### Config file

Verifies that the configuration file (default `config.toml` or the path set
via `CLEVERAGENTS_CONFIG_PATH`) exists and is readable.

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | File exists and is readable, or file is absent (defaults are used) | None required |
| error | File exists but is not readable | Fix file permissions: `chmod 644 <config_path>` |

### Data directory

Verifies that the data directory (from `Settings.data_dir`) exists and is
writable.

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | Directory exists and is writable | None required |
| warn | Directory does not exist | Create it: `mkdir -p <data_dir>` |
| error | Directory exists but is not writable | Fix permissions: `chmod 755 <data_dir>` or change ownership |

### Database

Verifies that the SQLite database file (or its parent directory for
first-run) is accessible and writable.

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | DB file is writable, or parent dir is writable (first run) | None required |
| ok | Non-SQLite database URL is configured | None required |
| error | DB file exists but is locked or not writable | Close other processes using the DB, or fix permissions |
| error | Parent directory is not writable | Fix parent directory permissions |

### Provider API keys

Checks whether each supported LLM provider has its API key configured.
One sub-check is emitted per provider.

| Provider | Environment variable | Status when missing |
|----------|---------------------|---------------------|
| OpenAI | `OPENAI_API_KEY` | warn |
| Anthropic | `ANTHROPIC_API_KEY` | warn |
| Google | `GOOGLE_API_KEY` | warn |
| Google Gemini | `GEMINI_API_KEY` | warn |
| Hugging Face | `HF_TOKEN` | warn |
| OpenRouter | `OPENROUTER_API_KEY` | warn |

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | API key is configured | None required |
| warn | API key is not set | Set the environment variable to enable the provider |

Missing provider keys are warnings, not errors, because the system can
operate with any single provider configured.

### Disk space

Checks available disk space on the volume containing the current working
directory.

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | >= 1.0 GB free | None required |
| warn | 0.5 -- 1.0 GB free | Free disk space or move data directory to a larger volume |
| error | < 0.5 GB free | Immediately free disk space to avoid data corruption |

### File permissions

Verifies read and write access to the data directory.

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | Data directory is readable and writable | None required |
| warn | Data directory does not exist | Create it (see Data directory check) |
| warn | Data directory is readable but not writable | Fix write permissions: `chmod u+w <data_dir>` |
| error | Data directory is not writable | Fix permissions or change ownership |

### Git

Checks that the `git` binary is available on `PATH`.

| Status | Condition | Remediation |
|--------|-----------|-------------|
| ok | `git --version` succeeds | None required |
| error | `git` is not found or times out | Install git for version control integration |

---

## Summary counts

The `summary` object in JSON/YAML output includes:

| Field | Type | Description |
|-------|------|-------------|
| `total` | int | Total number of individual checks run |
| `ok` | int | Checks that passed |
| `warnings` | int | Checks with non-critical issues |
| `errors` | int | Checks with critical issues |
| `duration_s` | float | Wall-clock seconds for the full diagnostic run |

## Recommendations

When a check returns `warn` or `error` and has an actionable fix, the
recommendation is collected into the `recommendations` list in the output.
Recommendations are ordered by check execution order.

## Using `--check` in CI

```bash
# Fail the pipeline if any critical check errors
agents diagnostics --check --format json
```

Exit code `0` means all checks passed (warnings are tolerated).
Exit code `1` means at least one check reported `error`.