Skip to main content
agentx scan reads your agent clients’ directories, their MCP configuration files and your skill library (~/.agents/skills), then prints what it finds. It changes none of these files. It starts MCP servers only when you ask for a handshake. A configuration is detected when its configuration directory exists, such as ~/.claude for Claude Code or ~/.cursor for Cursor. If agentx detects none, it prints No agent configurations detected.

Scan the machine

How to read it:
  • The first line counts the whole machine. A skill with the same content in several configurations counts once, and so does a server declared in several. A plugin counts once for each configuration it is installed in.
  • Each agent configuration then gets a section. Its first line shows the client name, its id, its configuration directory, enabled or disabled, and how many skills, servers and plugins it has. An enabled configuration gets new skills by default; see Enable or disable a configuration.
  • skills: lists every skill the configuration can see, one per line: the skill name, its kind, its scope (user, or project with --project) and the path the client reads. A skill from a plugin ends with (plugin <name>).
  • servers: appears when the configuration declares MCP servers, one per line: the name, the transport (stdio, sse or streamable-http) and the command line or URL. A server from a plugin ends with (plugin <name>), and a server turned off in its client shows (disabled). After a handshake, the row also shows a count or why the handshake failed.
  • plugins: appears when the configuration has plugins, one per line: the name, the version, how many skills and servers the plugin provides here, and (disabled) when the client has turned it off.
agentx cleans text from files it did not write before it prints it. See Text output.

Read the kind

See who reads what

A client can read other clients’ directories. Cursor reads ~/.claude/skills and ~/.codex/skills next to its own ~/.cursor/skills, so a skill you put in the Claude Code directory appears under Cursor too. Some clients, such as Codex and Gemini CLI, read the library at ~/.agents/skills directly, so every library skill appears under them without any link in their own directories.

Read the servers

agentx reads the user-scope MCP configuration of Claude Code (~/.claude.json), Codex (~/.codex/config.toml), Cursor (~/.cursor/mcp.json), Gemini CLI (~/.gemini/settings.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and GitHub Copilot (~/.copilot/mcp-config.json). Other clients contribute skills only. The inventory shows the command and arguments of a local server and the URL of a remote one. It hides the values of environment variables and headers. A secret written directly into a command argument or a URL still appears. agentx counts a server declared in several clients as one server. It recognises a remote server by its URL, and a local npx, uvx, pipx or docker server by its package or image, whatever the version. It recognises any other local server by its exact command line on this machine.

Handshake the servers

A handshake starts or connects to every MCP server and records the tools, prompts and resources it offers. The count on the row includes all of them. Each server gets ten seconds. agentx runs each server the way the client that declares it does:
  • agentx fills in placeholders such as ${API_KEY} from your environment, the way the declaring client does. The inventory shows the declaration as written.
  • For a remote server that Claude Code declares, agentx leaves Claude Code’s credential variables empty in the URL and headers, as Claude Code does. These include AWS_SECRET_ACCESS_KEY and every ANTHROPIC_* and CLAUDE_* variable. Run with --verbose to see which ones agentx left empty.
  • A remote server receives its declared headers at its declared URL. For Codex, agentx reads the values of env_http_headers and bearer_token_env_var from your environment.
  • agentx skips a server you turned off in its client, and its row shows (disabled). agentx reads this setting from Codex (enabled = false), Gemini CLI (mcp.excluded, mcp.allowed and gemini mcp disable) and GitHub Copilot (/mcp disable). Claude Code, Cursor and Windsurf store it where agentx cannot read it, so agentx handshakes those servers.
agentx compares what each server offers. Two servers with the same command or URL but different tools count as two servers. The same server declared in two clients with the same tools stays one server. agentx keeps the results in handshakes.json in agentx home, ~/.agentx by default. A later scan without --handshake shows them until the next handshake replaces them.

Fix a failed handshake

When a handshake fails, the server’s row says why, a warning names its file, and a hint says what to do. The server keeps the results of its last successful handshake, if any, and the scan still succeeds.

Read the plugins

Plugins are listed under the configuration they are installed in, with their version. The skills and MCP servers a plugin provides appear in the configuration’s list like any other, marked with the plugin’s name. A skill installed both on its own and through a plugin, with the same content, counts as one skill and appears on two rows. A plugin’s version is what its manifest or install record says. Without one, a Codex plugin or a Cursor marketplace plugin shows its cache directory name, such as local or a commit id.

Hooks and icons

With --json, each plugin also lists its hooks and carries its icon, so that the desktop app can show them without reading the plugin’s files:
  • hooks lists one entry per hook the plugin declares, with the event it runs on and a name. agentx reads the plugin’s hooks/hooks.json and the hooks its manifest declares, and never reports a hook’s command line. A hook has no name of its own in any client, so agentx names it after its status message when it has one, else after the script or program it runs, else after what it is (prompt, agent, http, or the tool of an MCP tool hook).
  • icon is the plugin’s own icon, as a data URL you can put in an <img>, when the manifest names an image file inside the plugin: icon for Claude Code, logo for Cursor, interface.logo or interface.composerIcon for Codex. The file must be a PNG, a JPEG or an SVG of at most 64 KiB. agentx removes scripts and event handlers from an SVG before carrying it. A plugin whose manifest names no image, an image outside the plugin, over the limit or in another format, or an image at a URL, which agentx never fetches, has no icon.

Include a project

Adds the skills in the project’s own skills directories, such as .claude/skills, .cursor/skills and .agents/skills. Their scope is project. agentx only reads the project. Without the flag, agentx scans only your user directories, scope user.

Rescan after a change

--configuration names the configuration that changed. agentx checks that the id is detected, then scans the whole machine as usual. An id that is not detected exits with code 5 and lists the detected ids.

Warnings

These problems do not stop the scan. agentx prints each one on stderr as warning: ... after the inventory:
  • An MCP configuration file that cannot be parsed.
  • A server whose handshake failed. See Fix a failed handshake.
  • A plugin manifest that cannot be read. The warning names the file.
  • A Cursor plugin copy that Cursor did not finish writing: agentx does not list it. A Cursor plugin manifest path that leads outside the plugin: agentx skips that path.
  • A plugin hooks file that cannot be read, or a plugin icon that leads outside the plugin, is over 64 KiB, is missing or is not a PNG, a JPEG or an SVG: agentx reports the plugin without it. The warning names the manifest.
  • A broken symlink in a skills directory: agentx skips it.
  • A SKILL.md whose frontmatter is not valid YAML or has no name: agentx names the skill after its directory.
  • A symlink inside a skill that points outside the skill: agentx skips that file.
Several broken symlinks in one skills directory make one warning that names the directory and lists the links:
Delete the listed links to clear the warning.