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.

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

Read the last block first: it repeats every warning and failure with its fix.

The rows are grouped by what they check:

• System: git and the home directory.
• App: agentx’s own state.
• Clients: 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. The source_remotes and staged_imports rows appear only once the account repo exists; on a fresh machine there is nothing to read.

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.

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

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.