Skip to main content

​
Text output

Every command prints aligned text for you to read. Tables pad their columns, a row that reports a state starts with a glyph (✓ ok, ! warning, ✗ failure, • information), and a command that changes something confirms it on one line:
Text that comes from somewhere else is cleaned before it is printed: tabs, newlines and other control characters become spaces, so one item stays one row and nothing can take over your terminal. That covers:
  • the name and description a source writes for its skills, and the directory it keeps each one in;
  • the name of a directory in your library or your client’s configuration;
  • the command line an MCP server is declared with;
  • what agentx passes on from other programs, including the messages a git server sends back when you add a source.
Paths are quoted instead of cleaned, so you can still copy one. A path holding a control character is printed in double quotes with escapes, the way git status prints such a path:

​
Colour

Text output is coloured when it goes to a terminal. Each colour means one thing everywhere: green for ok and enabled, yellow for a warning, a hint and disabled, red for a failure and an error, blue for information, cyan for a key or a flag name, and dim for secondary detail. Output piped into another program or a file carries no colour, so the text a script reads is the same as before. Control it explicitly with the global --color flag:
Set the NO_COLOR environment variable to any value to turn colour off in every terminal.

​
Logs

Logs go to stderr, never to stdout. A line starting warning: is something to look at, and one starting info: is a note that asks nothing of you, such as a failure warned about earlier that has ended. Add --verbose to see debug lines too, such as which agentx home and library the command used. Some warnings put what to do on a second line, indented under the warning.

​
Errors

A failed command prints error: ... and, when there is a fix, hint: ... on stderr.

​
Exit codes

​
Stop a run

Press Ctrl-C, or send SIGTERM, to stop a run. agentx stops the git command it is waiting on, prints error: interrupted with a hint, and exits 9:
A change that had already started is finished before the run stops, and one that had not started leaves nothing behind. The exception is a stop sent to the whole process group agentx runs in, most commonly Ctrl-C in a terminal. Such a stop also reaches the git command agentx is running, so a change caught while it was being written to the account repo can stop part way. That is safe: agentx writes down what it is about to do before it does it, the next agentx command finishes or rolls it back, and agentx doctor tells you one is waiting. Run the command again when you are ready. Press Ctrl-C a second time to kill the run outright. That is safe for the same reason: the next agentx command finishes or rolls back what the killed run left, and agentx doctor shows whether anything is waiting. A run that had already finished everything you asked for exits 0: the signal arrived too late to change the outcome, and agentx reports what it did. Run agentx in the background from a script and Ctrl-C in that terminal leaves it alone, exactly as it leaves every other background job alone.

​
Directories

Set either to move that directory. agentx reads HOME and XDG_CONFIG_HOME to find your agent clients.

​
JSON output

Add --json to any command to get one JSON object per line instead of text. The agentx desktop app reads this output; you do not need it to use agentx from a terminal.