agentx doctor - agentx

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

agentx doctor

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:

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

agentx --json doctor

{"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.

​What it checks

​Exit codes

​Script it

What it checks

Exit codes

Script it