AgentUX

Portable Multi-Agent UX Stress-Tester for local web apps.

Goal

Install once, then run AgentUX from any project root to audit that project's running app.

Install

pip install -e .
playwright install chromium

Install Anywhere

You have three practical options:

1. Direct from local path (dev mode)

pip install -e /absolute/path/to/ux-tester

2. Isolated global CLI via pipx (recommended for tool-style usage)

pipx install /absolute/path/to/ux-tester

3. Build wheel and install on another machine

python -m pip install build
python -m build
pip install dist/agentux-0.1.0-py3-none-any.whl

Use In Any Project

From the target project's root directory:

1. Install AgentUX

pip install agentux

2. Initialize AgentUX (sets key + infers project context/scenario)

agentux init

3. Start your web app (framework-specific)

# examples:
npm run dev
# or
pnpm dev
# or
python manage.py runserver

4. Run AgentUX

agentux run

agentux run:

• Requires .agentux/ to already exist (created by agentux init)
• Ensures Playwright Chromium is installed (unless --skip-browser-install)
• Starts dashboard and auto-starts audit

Optional:

agentux run --no-auto

Run:

agentux run

Open http://localhost:8501.

Features

• Discovery + dynamic persona synthesis
• Parallel persona audit loops with Playwright
• Structured observability artifacts (screenshots, traces, JSONL logs)
• Streamlit mission-control dashboard
• Final UX friction report (report.md + report.json)

Artifact Output

Each run writes under the current project's .agentux:

.agentux/artifacts/<run_id>/
  config_snapshot.json
  discovery/
  agents/<agent_id>/
  aggregate/

Scenario config is read from .agentux/scenarios/default.yaml. Login credentials are read on-demand from .agentux/login.yaml when agents need to fill auth forms. Use this format:

accounts:
  - username: student@example.com
    password: your-password
  - username: teacher@example.com
    password: your-password

Inference details are saved to .agentux/project_profile.json. Example:

default_scenario:
  id: "default"
  name: "Checkout Flow"
  goal: "Complete a purchase"
  success_assertions:
    - type: "url_contains"
      value: "/checkout/complete"
persona_overrides: {}

Optional Docker Dev Mode

docker-compose up --build

Notes

• agentux init updates .gitignore with .agentux/.env, .agentux/login.yaml, and .agentux/artifacts/.
• The engine fails fast on missing API key or unreachable target URL.
• Your target app must already be running before agentux run.