ajx.

Set up AJX and run a first useful trial

AJX tests how agents experience a product. Give a fresh worker a task, observe the attempt, verify its outcome, and turn the friction into evidence-backed product improvements. A successful task can still reveal a difficult experience.

If a user pointed you here, help them set up AJX and use it on their project. Start with one task and one attempt. Reuse any task, permissions, and cost limits they already supplied. This page bootstraps the stable release; its installed skill is the authority for running that release.

This guide as Markdown · Site overview · All essential text · Structured content map

Check the prerequisites

Check command -v ajx and run ajx version if available. Check the operating system and architecture before installing. Inspect existing skill paths without reading credential values. If shell access or a supported platform is missing, explain that blocker instead of claiming setup succeeded.

Install the CLI and skill together

Run this in Bash or Zsh for a new installation:

bash -o pipefail -c 'curl -fsSL https://github.com/royosherove/ajx/releases/latest/download/install.sh | bash' && export PATH="$HOME/.local/bin:$PATH"

The installer downloads the native package from the latest stable public GitHub Release and verifies its checksum. It installs the CLI and the complete matching skill. Do not clone an unreleased source branch or copy only SKILL.md as an installation shortcut.

Confirm the installation:

"$HOME/.local/bin/ajx" version
"$HOME/.local/bin/ajx" --help

Use the absolute path if your shell tool starts a new process for each command; an earlier export PATH may not persist. Report the actual installed version and locations.

If an existing skill blocks installation

Preserve customized files. If the user chooses to replace the conflicting installation, use this complete command. --replace backs up the conflicting files to adjacent .ajx-backup-* paths: 

bash -o pipefail -c 'curl -fsSL https://github.com/royosherove/ajx/releases/latest/download/install.sh | bash -s -- --replace' && export PATH="$HOME/.local/bin:$PATH"

Do not delete the old skill to bypass the installer.

Update an existing managed installation

Check without making changes:

"$HOME/.local/bin/ajx" update --check --json

To install an available stable update with its matching skill:

"$HOME/.local/bin/ajx" update --with-skills

Interactive ajx update offers the CLI and skill choices. Do not automatically downgrade a newer development build.

Read the installed skill

For the default installation, read:

~/.local/share/ajx/current/skill/SKILL.md

Resolve relative references from that skill/ directory. The installer registers the skill at ~/.agents/skills/ajx, ~/.claude/skills/ajx, and ~/.kiro/skills/ajx. For a custom installation, use the paths printed by its installer.

A session opened before installation may not list /ajx yet. Read the file and continue in the same chat when the host allows it. If the host requires a new session, give the user a resume prompt with the skill path, project, task, decisions made, and next step. A custom Kiro agent may need an explicit skill resource entry; follow the harness guide.

Prepare one real attempt

  1. Choose a small task. Reuse the user’s goal and materials. Keep the prompt neutral: do not audit the product or reveal suspected defects before the worker attempts it.
  2. Define success. Use a deterministic check of the requested outcome. “The worker finished” and “a file exists” may not prove the task succeeded.
  3. Choose the conditions. Start with one supported worker, one model, one reporter, and one attempt. Confirm filesystem and network access, time limits, and model costs. A local workspace is not a sandbox. Use the installed skill’s environment guidance for local Docker isolation.
  4. Prepare and check the trial. Follow the installed skill to write the briefing and trial files. Run validate and doctor; resolve missing tools, authentication, and verification checks before launch.
  5. Review and run. Show the task, success check, access, and expected costs. Open the local AJX Console for review, or use the installed skill’s chat approval flow. Start once the scope is authorized.

Do the setup work the user authorized. Ask only for missing decisions or actions you cannot complete, such as provider sign-in. Never request pasted secrets or make paid model calls just to probe authentication.

Direct CLI workflow

These commands scaffold and check a trial. Run them from the project directory. Use a new trial folder if trials/my-product already exists: 

ajx init trials/my-product --product my-product --harness codex --no-input

Stop to edit the scaffold: set the real task in trials/my-product/task-prompt.md and configure the product materials, environment, permissions, and success checks in trials/my-product/trial.toml. Use claude-code or kiro-cli instead of codex when appropriate. Prefer a model supported by the selected harness; consult the installed release’s help.

Then check the configuration and open the console:

ajx validate trials/my-product/trial.toml
ajx doctor trials/my-product/trial.toml
ajx console trials/my-product

The console lets the user review, start, and watch the trial. For an already authorized headless attempt, use ajx run trials/my-product/trial.toml. Do not interpret that command’s exit code alone as verified task success.

Read the result

Open the generated matrix index.html, the run’s report.html, and pretty-journey.html. Lead with the verified outcome and the most useful product asks. Explain the evidence and how the team can check a fix.

Keep real reports local unless the user asks to share them. They may contain private project content. Explain blocked execution, incomplete reporting, or unconfirmed cleanup. For another product revision, use a new output directory; reusing an old output can resume its previous attempt.

Try without model calls

To explore AJX before configuring a worker, run this simulated console demo in a new directory: 

"$HOME/.local/bin/ajx" console demo trials/console-demo

Open the printed console URL and press Check and start. This demo uses no worker credentials or model calls. It does not test the user’s project.

For static fictional reports:

"$HOME/.local/bin/ajx" example trials/example

Open trials/example/index.html. You can also browse the website’s sample matrix, sample report, and sample journey. All sample events, metrics, and outcomes are invented.

Run an already briefed trial in CI

Prepare the trial, deterministic checks, acceptance policy, worker tools, and noninteractive authentication first. Then run: 

AJX_RESULTS_DIR="$(mktemp -d)"
ajx ci usability/trial.toml --output "$AJX_RESULTS_DIR" \
  --policy usability/acceptance.toml --timeout-grace 60 </dev/null

Here usability/trial.toml and usability/acceptance.toml are your prepared files, not files installed by AJX. Collect ci-result.json and junit.xml from the output directory. The CI command evaluates verified task outcomes and returns a passed, failed, or inconclusive decision. It cannot make interactive provider login unattended.

See CI options and the acceptance-policy format.

Scope and sources

Shipped capabilities include local and local Docker execution, selectable worker skills, supported harness adapters, a local live console, structured artifacts, and headless absolute acceptance checks. Remote provisioning, remote shared dashboards, selected plugins/hooks, baseline regression gates, and automatic product-improvement loops remain designs.

Use the installed release’s skill and --help if they differ from website examples. These instructions were checked against public AJX source commit 5cec0dc84a0a8eb029257d7c4bb6f486c703a694: