Build reliable command-mode automation

Reliable Autohand Code automation combines a bounded task, an appropriate permission policy, captured output, and independent validation of the result. Command mode runs a single instruction with -p. Structured transport output helps a script observe the run; it does not prove the requested code change is correct.

Verify the local command surface

autohand --version
autohand --help

The examples below use -p, --restricted, and --output-format stream-json. Check them against your installed version and the CLI reference. Authentication and provider access must be configured in the environment where the command actually runs.

Begin with a bounded read-only task

autohand --restricted -p "Read AGENTS.md and summarize the test commands. Do not edit files."

Restricted execution may deny an operation the agent attempts. Inspect the report; denied work is not completed work. For automation that must write files, choose and document a policy that permits those specific operations instead of silently bypassing approvals.

Capture output and preserve failure status

The following example runs in a POSIX shell. It saves transport events to a file and returns the command's failure status:

mkdir -p artifacts
if autohand --restricted \
  --output-format stream-json \
  -p "Inspect src/tasks.js for edge cases. Do not edit files. Cite each finding." \
  > artifacts/review.jsonl; then
  echo "Review command completed; inspect artifacts/review.jsonl"
else
  result=$?
  echo "Review command failed with status $result" >&2
  exit "$result"
fi

Do not parse line-oriented events as a single JSON document or assume an undocumented event layout. See headless mode and pipe mode for transport details.

Validate the deliverable separately

Evidence	What it proves	What it does not prove
Process exit status	The command reported success or failure	The requested feature is correct
Captured events	The output available to the caller	A suggested check actually ran
Test results	The exercised assertions passed	Untested requirements are satisfied
Reviewed diff	Which files and behavior changed	Deployment or live service behavior

For a coding task, run the repository's tests and build after the command returns. Keep generated files and logs as artifacts only after reviewing them for secrets. A retry can duplicate external writes, so prefer disposable workspaces and tasks with no remote side effects when first building an automation.

Troubleshooting and checkpoint

If the command waits for input, inspect whether its policy or credential setup still requires interaction. If output is empty, check the exit status and stderr before retrying. If tests pass but a required artifact is missing, treat the task as incomplete. Practice deterministic checks in automate a validation check.

Frequently asked question

Does a successful agent process prove that a feature works?

No. The process result must be followed by validation of the requested deliverable: inspect changed files, run repository checks, and verify any behavior that requires a browser or external service.