agentx serve

agentx serve is what the desktop app runs in the background. It scans the machine once, then rescans when a skill or agentx’s own state changes. It reports again only when the inventory changed. It also checks your skills for updates when it starts. You rarely need to run it yourself. This page uses the terms agentx home (~/.agentx) and account repo.

Run it

agentx serve

inventory 1: 3 configurations, 5 skills
update pdf: 3f2a9c1 -> 8b1e0f4, 2 files
inventory 2: 3 configurations, 5 skills

The first inventory line is the inventory when serve starts. Each later inventory line means the inventory changed. A change that leaves the inventory as it was prints nothing. Each update line is a skill with an update available. To stop serve, press Ctrl-C or close its stdin. Serve then exits with code 0. The desktop app runs serve with --json. The JSON output also carries the whole inventory and a notice each time a skill changes state.

What counts as a change

Serve watches agentx home (~/.agentx), the library and the skills directory of every agent client agentx knows, such as ~/.claude/skills. It does not watch the clients’ MCP configuration files: a change there shows at the next rescan. Serve sees a skill added, removed or edited, whatever tool made the change. The next inventory shows it. A skill of your own shows as modified as soon as you edit it, and as current again once you publish it with agentx skill publish. A commit you make with Git does not publish your edits. Serve never publishes or commits for you.

What serve repairs at start

When serve starts, it checks each skill on disk and repairs what it can. It prints one line for each skill that needs attention. A skill that is fine prints no line:

reconcile beta: modified
reconcile release-notes: repaired
inventory 1: 3 configurations, 6 skills

Outcome	What it means	What to do
`repaired`	One of your own skills had a missing or broken worktree or library symlink, for example after you moved `~/.agentx`. Serve checked it out again from its branch.	Nothing.
`worktree missing`	Serve could not repair one of your own skills. A Git command you ran in its worktree, such as a merge, is unfinished, or the worktree is on another branch.	Finish or abort the Git command, or switch the worktree back to the skill’s branch. Then run `agentx skill place <name>`.
`adopt candidate`	A folder of yours is where one of your own skills belongs. Serve leaves it as it is.	Adopt it with `agentx skill place <name> --force`.
`modified`	You edited a skill you installed from a source.	Nothing.
`installable`	A skill you installed whose folder is gone, or one of your own skills that is not placed on this machine.	Install a skill of a source again with `agentx skill add <source> --name <name>`, or stop managing it with `agentx skill remove <name>`. Place one of your own skills with `agentx skill place <name>`, or install it from your account remote with `agentx skill add --name <name>`.
`unmanaged`	A folder in your library that no source manages.	Nothing.

An edited skill of your own prints no line here. agentx skill list shows it as modified until you publish your edits. Serve repairs only what is missing or broken. It does not delete or overwrite your files.

Update checks

When serve starts, it checks your managed skills for updates once, right after the first inventory, as agentx skill check-updates does. To check again later, run agentx skill check-updates. The check runs in the background, so scans go on while it waits on the network. The check also:

Fetches every source you added, as agentx source fetch --all does, including sources you have not installed from.
Fetches your account remote when one of your own skills is placed on this machine, and reports what your other machines published to it.

The check only records what it found. Apply an update with agentx skill update. A source that cannot be fetched, because you are offline or the repository moved, is a warning starting update check: that names it and any skills it left unchecked:

warning: update check: https://github.com/me/skills: git fetch: fatal: unable to access 'https://github.com/me/skills/': Could not resolve host: github.com; not checked: pdf

Serve keeps running. Other update check: warnings name a skill or source the check could not check, and say what to do next. Serve does not fetch a source that your settings name and this machine never added, for example because an agentx import stopped before it added it. Its warning says source not fetched. Run agentx source add <url>, or the import again. For a pinned source, run agentx source add <url>#<ref> so it keeps its pin.

Maintenance

When serve starts, it tidies the account repo (~/.agentx/account.git) in the background, at most once a day. It deletes nothing.

Run one pass

agentx serve --once

Serve scans once, prints the inventory and exits. It repairs nothing, watches nothing and runs no update check or maintenance. To read the full inventory, run agentx scan.

One serve per home

Only one serve runs for each agentx home (~/.agentx). A second agentx serve, --once included, exits with code 6 and names the lock file, ~/.agentx/serve.lock. Stop the running serve first.

When watching is not possible

If a directory cannot be watched, serve exits with code 6 and an error naming the directory and the cause. On Linux this usually means the inotify watch limit is reached. Raise fs.inotify.max_user_watches. On macOS, use the released binary or the Homebrew build. A binary built from source without cgo soon reaches the default open-file limit. Raise it with ulimit -n. Serve cannot watch a skills directory that does not exist yet. When another change causes a rescan, serve finds the new directory and watches it from then on.

Get started

Inventory

Skills

This machine

Reference