Skip to main content

​
Text output

Without --json, 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 drive 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, and what agentx relays of what something else said, 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:
Read any value exactly as it was written with --json, which escapes it instead of cleaning it.

​
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. --json output is never coloured.

​
JSON output

Add --json before or after any command to get one JSON object per line on stdout. Every object has a type and an integer schema_version. The last line is always a result with ok set to true or false.
Parse each line on its own. Read the exit code before trusting the output.

​
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. With --json, log lines are JSON objects too, and each one’s level is warn, info or debug. More levels may be added later, so show one you do not know as it is written. Some warnings put what to do on a second line, indented under the warning. With --json, such a warning is still one log event, and its message holds both lines joined by ; .

​
Errors

A failed command prints error: ... and, when there is a fix, hint: ... on stderr. With --json it emits an error event with code, message and hint instead, followed by a result with ok: false.

​
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.