> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentx.wft/llms.txt
> Use this file to discover all available pages before exploring further.

# agentx doctor

> Check that agentx can run: git, agentx home and the account repo.

Run `agentx doctor` before your first install, or whenever something looks wrong. It only reads: it never creates or changes anything in agentx home.

```sh theme={null}
agentx doctor
```

```text theme={null}
System
  ✓ git                 ok    git 2.43.0
  ✓ fork_merges         ok    upstream changes can be merged into forks
  ✓ commit_identity     ok    commits get the same id on every machine
  ✓ home                ok    not created yet: /home/me/.agentx; the first scan creates it

App
  ✓ lock                ok    no other agentx command is running
  ✓ mutations           ok    no interrupted changes
  ✓ settings            ok    defaults: /home/me/.agentx/settings.json is not written yet
  ✓ account_repo        ok    not created yet: /home/me/.agentx/account.git
  ✓ library             ok    not created yet: /home/me/.agents/skills; the first install creates it

Clients  2 of 75 registered clients detected
  • client:claude-code  info  Claude Code: /home/me/.claude
  • client:cursor       info  Cursor: /home/me/.cursor

✓ No issues detected
```

When a row is `warn` or `fail`, the report ends with an issues block instead, repeating each one with its fix:

```text theme={null}
1 issue
  ! lock  held by process 4242: /home/me/.agentx/lock
          hint: wait for it to finish
```

The `source_remotes` and `staged_imports` rows appear only once the account repo exists; on a fresh machine there is nothing to read. The rows are grouped by what they check: `System` is git and the home directory, `App` is agentx's own state, `Clients` is every detected agent configuration, with the count in the title. In a terminal the rows are coloured by status: green for `ok`, yellow for `warn`, red for `fail`, blue for `info`. Read the last block first: it repeats every warning and failure with its fix.

## What it checks

| Check | Meaning |
| - | - |
| `git` | git is in `PATH` and at least 2.40. |
| `fork_merges` | git can merge upstream changes into forks, which updates need. |
| `commit_identity` | agentx commits get the same id on every machine, whatever your git configuration. |
| `home` | agentx home is writable, or does not exist yet. The first scan creates it. |
| `lock` | No other agentx command holds the lock. When one does, the detail names its process id. |
| `mutations` | No change to agentx home was cut short by a crash. When one was, the detail names its journal; run `agentx scan` to finish it. If that refuses because the file changed meanwhile, restore the file or move the journal aside. Doctor only reports. |
| `settings` | `settings.json` is valid. |
| `account_repo` | The account repo opens, or does not exist yet. The first command that needs it creates it: `agentx source add`, `agentx skill add` of a source not added yet or with `--fetch`, or `agentx adopt` of a skill whose source is not added yet. |
| `source_remotes` | Every source remote in the account repo belongs to a source your settings list. An add that fails clears its own remote, so this row names one only when a run was killed outright or its cleanup was refused. Run `agentx source add` with the URL the row names to add the source and take the remote with it, or `agentx source remove <id>` to clear it. A remote whose URL agentx would not have written, one carrying a token for instance, is named by its source id instead, so the URL is never printed. |
| `staged_imports` | No import is left staged. An install or an update check killed between writing its commits and publishing them leaves refs under `refs/agentx/importing/`, which hold on to the objects they name. Remove each with the `git update-ref -d` command in the hint, while no agentx command is running and `agentx serve` is stopped. |
| `library` | The library is a writable directory, or does not exist yet. The first install creates it. |
| `client:<id>` | One row per detected agent configuration, naming the client and its configuration directory. |
| `clients` | How many of the clients agentx knows are detected. A warning when none is: install an agent client, or check that `HOME` points at the right user. |

Each row is `ok`, `warn`, `fail` or `info`, marked `✓`, `!`, `✗` or `•`. Every `warn` and `fail` row is listed again at the end under `<n> issues`, with its fix as a `hint:` line under the detail.

## Exit codes

* `2`: git is missing or older than 2.40. The hint names the fix; on Ubuntu 22.04, which ships git 2.34, install a newer git or upgrade the distribution. Every other command except `version` refuses to run until git is fixed.
* `8`: `account.git` in agentx home exists but is not a repository git can read. Check the directory, or move it aside.
* `9`: you stopped the run with Ctrl-C. See [Output and exit codes](/cli/output).
* `0`: everything else, warnings included.

## Script it

Add `--json` to get one `doctor` event per check with `check`, `status`, `detail` and, when there is a fix, `hint`:

```sh theme={null}
agentx --json doctor
```

```json theme={null}
{"type":"doctor","schema_version":1,"check":"git","status":"ok","detail":"git 2.43.0"}
{"type":"doctor","schema_version":1,"check":"lock","status":"warn","detail":"held by process 4242: /home/me/.agentx/lock","hint":"wait for it to finish"}
{"type":"result","schema_version":1,"ok":true}
```

Add `--verbose` to see every git command doctor ran and what git printed.


## Related topics

- [agentx scan](/cli/scan.md)
- [Output and exit codes](/cli/output.md)
- [agentx source](/cli/source.md)
- [agentx](/index.md)
- [agentx skill](/cli/skill.md)