agentx config

List, get and set the settings of one machine.

Machine settings live in settings.json in agentx home, ~/.agentx by default. They never leave the machine.

List every setting

agentx config list

schema_version           1
label                    my-laptop
auto_push                false
accept_operations        false
ignore_system_files      true
disabled_configurations  (none)
sources                  []
copy_mode                {}

An empty setting shows as (none). In a terminal the keys are cyan and true is green.

Key	Meaning
schema_version	The settings file format version.
label	The machine label. Until you set it, it is the hostname.
auto_push	Whether published forks are pushed automatically.
accept_operations	Whether the machine executes operations queued for it.
ignore_system_files	Whether the files your operating system or editor leaves in a skill, such as .DS_Store, Thumbs.db, *.swp and *~ backups, are ignored when agentx compares, diffs and reverts it. On by default. See Files that do not count.
disabled_configurations	The agent configurations left out of placements by default. Every other detected configuration is enabled.
sources	The sources skills are installed from, managed with agentx source.
copy_mode	The skills placed as a copy instead of a symlink, per configuration. Written by agentx skill add --copy and agentx skill place --copy, and cleared by agentx skill remove.

Get one setting

agentx config get label

The command prints the bare value, so a script can use it directly. An unknown key exits with code 1 and lists the keys.

Set a setting

agentx config set label "work laptop"
agentx config set auto_push true

✓ label is now work laptop

You can set label, auto_push, accept_operations and ignore_system_files:

• auto_push, accept_operations and ignore_system_files take true or false.
• A label is one non-empty line of at most 256 bytes with no control character in it.

Any other value, an unknown key, or a key this command cannot change exits with code 1.

The write is atomic: the file is replaced whole, or not at all. If another agentx command is running, the command exits with code 7 at once; retry when it finishes.

Enable or disable a configuration

agentx config disable windsurf
agentx config enable windsurf

✓ windsurf is now disabled
✓ windsurf is now enabled

Every agent configuration agentx scan detects is enabled from the start. Disable one to leave it out of placements by default; enable it to put it back. Use the id shown in parentheses by agentx scan. An id that is not detected exits with code 5 and lists the detected ids. Disabling a configuration does not stop its client from reading the library.

Enabling only decides where later installs go. To fill a newly enabled client with what you already have, add --place-all:

agentx config enable cursor --place-all

✓ cursor is now enabled
✓ placed 2 skills in cursor
  pdf   symlink  ~/.cursor/skills/pdf -> ~/.agents/skills/pdf
  xlsx  symlink  ~/.cursor/skills/xlsx -> ~/.agents/skills/xlsx

Each skill placed gets one row: its placement in Cursor’s own skills directory. A skill Claude Code also holds is one row too, although Cursor reads Claude Code’s skills directory as well.

Each skill is placed as a symlink, except in a configuration where agentx already keeps a copy of it: that one gets a copy again, as with agentx skill place.

The setting and every placement it implies are one change, written down before anything on disk moves. A run interrupted part way is finished by the next agentx command rather than undone.

A placement agentx cannot make does not fail the run. Something you put there yourself may already be at one of the paths, or agentx may be unable to write the client’s skills directory. Either way, agentx leaves that path alone and names it, places the rest, and still succeeds. The client can then end up enabled with only part of the library in it:

warning: ~/.cursor/skills/pdf is not this skill and was left as it is; no placement was made for cursor
✓ cursor is now enabled
✓ placed 1 skill in cursor, 1 placement skipped
  xlsx  symlink  ~/.cursor/skills/xlsx -> ~/.agents/skills/xlsx

Here Cursor does not see pdf at all, so pdf has no row. If agentx left Cursor’s path alone and Cursor still sees the skill through another client’s skills directory, as it sees a skill Claude Code holds, the skill’s row shows that path instead, so the output still tells you Cursor has the skill.

A copy agentx keeps for the client is skipped the same way when it is different from the library, for instance because you edited it. It stays exactly as it is, and the line under the warning names the commands that replace it with the library version:

warning: cursor's copy of pdf is different from the library, so it was left unchanged (~/.cursor/skills/pdf)
  to replace it with the library version: agentx skill remove pdf --from cursor && agentx skill place pdf --to cursor --copy
✓ cursor is now enabled
✓ placed 1 skill in cursor, 1 placement skipped
  xlsx  symlink  ~/.cursor/skills/xlsx -> ~/.agents/skills/xlsx

The kept copy is not the library’s pdf, so pdf has no row here either. If Cursor also sees pdf through another client’s skills directory, pdf’s row shows that path, as above.

See A copy that differs from the library.

--place-all belongs to enable; agentx config disable --place-all exits with code 1. Place skills one at a time with agentx skill place.

A client that reads the library directly, such as Codex, already sees every library skill, so --place-all makes no entry of its own for it and says so:

✓ codex is now enabled
✓ codex reads the library and already sees 2 skills; nothing was placed
  pdf   library  ~/.agents/skills/pdf
  xlsx  library  ~/.agents/skills/xlsx

Fix a broken file

If settings.json cannot be parsed, every config command exits with code 10 and names the file. Fix the JSON, or delete the file to start again from defaults.