@exodus/xqa

AI-powered QA agent CLI for Exodus applications.

Overview

xqa automates mobile app QA by connecting to physical devices or emulators and running intelligent exploration and spec-based testing. The CLI orchestrates the pipeline that spawns agents to interact with your app, capture screenshots, and generate findings based on user-defined specs or breadth-first exploration.

The tool manages configuration, project initialization, session state tracking, and interactive review workflows for triaging findings.

Commands

init

Initialize a new xqa project in the current directory.

Creates a .xqa/ directory with templates and subdirectories for specs, designs, and suites. Installs the xqa-spec skill for creating test specs.

xqa init

explore [prompt]

Run the explorer agent; omit prompt for a full breadth-first sweep.

Optional focus hint for the explorer agent. Omit to explore the entire app from the starting state. Generates a findings JSON file in .xqa/output/ and prints the path upon completion.

xqa explore                          # breadth-first exploration
xqa explore "test the login flow"    # focused exploration
xqa explore -v prompt,screen         # verbose output for categories
xqa explore -v                       # verbose output for all categories

Flag: -v, --verbose [categories] — Log categories (prompt, tools, screen, memory). Default: all if flag is present without value.

spec [spec-file]

Run the explorer agent against a spec file.

Loads a spec markdown file from .xqa/specs/ (or an absolute path) and executes the agent against it. Spec files define entry points, steps, and optional timeouts. Omit the argument to pick from available specs interactively.

xqa spec                                      # interactive spec picker
xqa spec .xqa/specs/authentication.test.md   # explicit spec file
xqa spec -v tools,memory                      # verbose output

Flag: -v, --verbose [categories] — Same as explore.

Spec file format (YAML frontmatter + markdown):

---
feature: 'Feature Name'
entry: 'Screen name or navigation path'
timeout: 300
---

# Spec content

review [findings-path]

Review findings and mark false positives.

Interactive session for triaging findings generated by explore or spec runs. Displays findings with confidence scores, steps, and screenshots. Mark findings as false positives (with optional reason) or undo previous dismissals. Saves dismissals to .xqa/dismissals.json. Defaults to the last findings path if omitted.

xqa review                                      # use last findings file
xqa review .xqa/output/findings-abc123.json    # explicit path

analyse [video-path]

Analyse a session recording with Gemini.

Requires GOOGLE_GENERATIVE_AI_API_KEY in environment. Analyzes a video file recorded during exploration and outputs findings as JSON.

xqa analyse /path/to/video.mp4

completion

Output shell completion script.

Generate completion script for bash or zsh. Pipe output to shell config file to enable tab completion.

xqa completion bash  # generate bash completions
xqa completion zsh   # generate zsh completions

Configuration

Configuration is loaded from environment variables and .env.local:

• ANTHROPIC_API_KEY (required) — Anthropic Claude API key for agent reasoning
• GOOGLE_GENERATIVE_AI_API_KEY (optional) — Google Generative AI key for video analysis
• QA_RUN_ID (optional) — Custom run identifier; defaults to auto-generated
• QA_EXPLORE_TIMEOUT_SECONDS (optional) — Exploration timeout in seconds
• QA_BUILD_ENV (optional) — Build environment: dev or prod (default: prod)

Architecture

Key files and directories:

• src/index.ts — CLI entry point; wires commander commands and manages graceful shutdown via process locks
• src/commands/ — Command implementations (init, explore, spec, review, analyse, completion)
• src/core/ — Pure functions: spec parsing, completion generation, verbose option parsing, last-path tracking
• src/shell/ — I/O wrappers: file reading, device discovery, app context loading
• src/config.ts, src/config-schema.ts — Configuration loading and validation with Zod
• src/review-session.ts — Interactive finding review loop with dismissal tracking
• src/spec-frontmatter.ts — Spec markdown frontmatter parsing (YAML)
• src/spec-slug.ts — Spec filename to slug derivation for output organization
• src/pid-lock.ts — Process-level mutual exclusion to prevent concurrent runs

Error Types

Core error discriminated unions:

• ConfigError — Configuration validation failed (INVALID_CONFIG)
• AppContextError — Failed to read app.md or explore.md (READ_FAILED)
• XqaDirectoryError — No .xqa directory found (XQA_NOT_INITIALIZED)
• SpecFrontmatterError — Malformed spec markdown (MISSING_FRONTMATTER, MISSING_FIELD, PARSE_ERROR)
• LastPathError — No findings path provided and no prior session (NO_ARG_AND_NO_STATE)

Development

Install dependencies:

pnpm install

Build the CLI:

pnpm run build

Run tests:

pnpm run test

Type check:

pnpm run typecheck

Lint and format:

pnpm run lint
pnpm run lint:fix

Full quality check (lint, typecheck, test):

pnpm run check
pnpm run check:fix

Watch mode (build + re-run on file changes):

pnpm run dev

Link binary globally (symlinks dist/xqa.cjs to ~/.local/bin/xqa):

pnpm run build:link

Unlink binary:

pnpm run build:unlink

Project Structure

src/
  index.ts                    # CLI entry point
  config.ts                   # Config loading and types
  config-schema.ts            # Zod schema for env vars
  constants.ts                # Tool lists and timeouts
  pid-lock.ts                 # Process exclusion lock
  spec-slug.ts                # Spec file to slug conversion
  spec-frontmatter.ts         # Spec YAML parsing
  review-session.ts           # Interactive finding review loop

  commands/
    init-command.ts           # Project initialization
    explore-command.ts        # Breadth-first exploration
    spec-command.ts           # Spec-based exploration
    review-command.ts         # Finding triage workflow
    analyse-command.ts        # Video analysis
    completion-command.ts     # Shell completion generation

  core/
    parse-verbose.ts          # Verbose flag parsing
    completion-generator.ts   # Bash/zsh completion script generation
    last-path.ts              # Last findings path tracking

  shell/
    app-context.ts            # Read app.md and explore.md
    xqa-directory.ts          # Locate .xqa directory

  __tests__/
    *.test.ts                 # Test files co-located with src/