agentx doctor

Run agentx doctor before your first install, or whenever something looks wrong.

agentx doctor

System
  ✓ git                 ok    git 2.43.0
  ✓ fork_merges         ok    upstream changes can be merged into your own skills
  ✓ 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

Read the report

If any row is warn or fail, the report ends with a list of issues in place of ✓ No issues detected. Each issue has its fix on a hint: line:

1 issue
  ! lock  held by process 4242: /home/me/.agentx/lock
          hint: wait for it to finish

Read this list first. 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.

Each row has a status and a mark. In a terminal, the mark and the status are coloured (see Colour):

Status	Mark	Colour
`ok`	`✓`	Green
`warn`	`!`	Yellow
`fail`	`✗`	Red
`info`	`•`	Blue

What it checks

Check	Meaning
`git`	git is in `PATH` and at least 2.40.
`fork_merges`	git can merge new versions from a skill’s source into skills you edited or forked. Updates need this.
`commit_identity`	agentx writes the same commits on every machine, so your machines agree on each skill’s version. Your git configuration does not change this.
`home`	agentx home is writable, or does not exist yet. agentx creates it the first time a command needs it, such as `agentx scan`.
`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, for example by a crash. If one was, the row names its journal, the file where agentx recorded the change. Run `agentx scan` to finish the change. If `scan` refuses, restore the file it names, or move the journal aside.
`settings`	`settings.json` is valid.
`account_repo`	The account repo opens, or does not exist yet. The first command that needs it creates it, such as `agentx source add`, `agentx skill add` or `agentx skill new`.
`source_remotes`	Every source remote in the account repo belongs to a source in your settings. A source remote is the link from the account repo to a source’s git repository. A killed run can leave a remote with no source. To fix it, run the command in the hint: it adds the source back with `agentx source add`, or clears the remote with `agentx source remove <id>`. If the URL may hold a token, the row shows the source id in its place.
`staged_imports`	No install or update check left unfinished data behind. A killed run can leave git refs (named pointers) under `refs/agentx/importing/`. They keep unused data in the account repo. To remove them, stop `agentx serve` and wait until no other agentx command runs. Then run the `git update-ref -d` command in the hint for each ref.
`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 agent clients agentx knows are on this machine. The text report shows the count next to the `Clients` title. If none is found, the check warns: install an agent client, or check that `HOME` points at the right user.

The source_remotes and staged_imports rows appear only when the account repo exists and opens. Add --verbose to see every git command doctor ran and what git printed.

Exit codes

doctor exits 0 even when some rows warn or fail. Only the git and account_repo checks, or a stop, give another code. See Exit codes for what each code means.

0: any other result, including warnings and other failed rows.
2: git is missing or older than 2.40. The hint names the fix. Ubuntu 22.04 ships git 2.34: install a newer git, or upgrade the distribution. Until you fix git, every other command except version and help refuses to run.
8: agentx cannot read account.git in agentx home as a git repository. Check the directory, or move it aside.
9: you stopped the run with Ctrl-C, or something sent it a SIGTERM. See Exit codes.

Get started

Inventory

Skills

This machine

Reference

Read the report

What it checks

Exit codes