Bash exit code, script output and file diffs in a chat card

What the agent can do

• Filesread_file, write_file, edit_file, grep, glob and list_dir work in the chat's working folder, and edit_file shows a diff of every change. A counter shows how many files were created, edited and read.
• Shellruns a command in the chosen environment, such as Windows, WSL or a server you own over SSH, and reports the real exit code. Dangerous commands are blocked.
• Webweb_search looks things up and http_get fetches one documentation page, so you can read what a command does before you use it.
• Screenshots and imagesocr reads text from a saved screenshot, for instance an error message, and gen_image saves image files.
• Orchestrationtask starts sub-agents in parallel, run_on_model sends a hard step to a bigger model, and skills are reusable playbooks.
• Approval modesAuto-run acts at once, Ask first pauses before actions that change something, and Plan only writes a plan and runs nothing.
• Cronruns a prompt on a schedule, for example a daily test run of your own script on a machine you own.
• Modelsa cloud AI provider through an API endpoint, a model on your PC, or the built-in model, which is ready without your own endpoint.

Four tasks with exit codes and arguments

Check the exit code when an argument is missing

You ask the agent to find out what happens when check.sh gets no argument. read_file opens the script, and Shell runs bash check.sh with nothing after the name. The card shows the real output and the exit code, which is 2 if the script prints its usage line to standard error and ends with exit 2. The bash exit code of the last command sits in $?, and the caller sees only that number, so a script that ends with a clear code is easier to test than one that always returns 1. Shell then runs the script again with two values, and the card should show 0. If the codes surprise you, read the card, then let edit_file propose a fix under Ask first and review the diff.

Parse options with getopts

You type “explain getopt to me” and the agent answers in plain words: getopts is a Bash builtin for short options such as -v or -f file, while getopt is a separate command that also handles long options such as --file and behaves differently between systems. Then read_file opens your script, edit_file adds a getopts loop and you see the diff. Shell runs the script with -v, with -f and with a wrong option, and each card has its own exit code. A wrong option should end with 2, the usual code for wrong usage. For a handful of options a while loop with case and shift is enough, so ask for that version if you prefer it. Accept the diff only after you have read it.

Keep values with spaces in one piece

Passing arguments with spaces to a script fails when the values are not quoted, because the shell splits them into separate words. The agent reads the file with read_file, finds the unquoted $1 and $@, and edit_file proposes double quotes around them. Shell then runs the script with a value such as "two words", and the output shows whether it arrives as one line or as two. One of the tricks to manage command line arguments is shift, which drops the first value so that a loop can walk through the rest, and the agent can add it in the same diff. Under Ask first the edit waits for you. Review the diff, run the test again and compare the two outputs yourself.

Stop on errors with set -eu

Anyone who searches for “bash exit script” is usually looking for the exit builtin: exit N ends the script with status N, while return N only leaves a function. The agent can add set -eu and set -o pipefail at the top, so the script stops on errors and on unset variables, and then it runs the file with bash -n for a syntax check and with bash -x to print each command. If return is not giving the status of the last command, another command usually ran in between, because $? holds only the exit code of the most recent one. The Shell card shows the trace. Read it from the top, compare it with the script and decide whether the edit stays.