QA Agent — Complete Client Guide

What This Does

QA Agent autonomously scans your entire codebase, writes test cases for every function, runs them, finds bugs, explains them clearly, and fixes them automatically — then asks for your approval before committing anything.

Supports: Python, Kotlin, Java, Vert.x, JavaScript, TypeScript, Go, Rust, React, Vue, ML/AI models, and more.

Prerequisites (Client Machine)

Privacy guarantee: Your code NEVER leaves your machine. The LLM runs locally via Ollama.

Install (One Command)

# Mac / Linux / Windows WSL:
curl -fsSL https://install.qa-agent.dev | bash

# Windows (PowerShell):
irm https://install.qa-agent.dev/windows | iex

This automatically:

1. Checks Docker is running
2. Starts all 7 AI services in Docker
3. Downloads LLM models (qwen2.5-coder — private, runs locally)
4. Installs the qa-agent CLI
5. Runs a health check

First Scan

# Go to your project directory
cd /path/to/your/codebase

# Run full autonomous scan
qa-agent scan .

What you'll see:

QA Agent — Autonomous scan
Repo: /path/to/your/codebase
Languages: all
Mode: exhaustive

[scanning]   Found 1,247 source files
[indexing]   Indexed 3,891 functions
[generating] Generated 3,891 test files (parallel, 4 workers)
[running]    2,847/3,891 tests passing
[healing]    Self-healed 891 wrong assertion values
[fixing]     Analysing 153 real failures...

┌─────────────────────────────────────────────┐
│  Bug Fix Proposal                           │
│  File: src/payment/calculator.kt            │
│  Confidence: 94%                            │
│                                             │
│  Root cause: Tax rate multiplied instead    │
│  of applied as percentage                   │
│                                             │
│  Diff:                                      │
│  - return amount * taxRate                  │
│  + return amount * (taxRate / 100.0)        │
└─────────────────────────────────────────────┘
Approve this patch? [y/N]: y

[PASS] Patch committed and verified.

╔══════════════════════════════════════════════╗
║         QA Agent — Scan Report               ║
║  Status: PASS                                ║
║  Files scanned:    1,247                     ║
║  Functions tested: 3,891                     ║
║  Tests passed:     3,891 / 3,891  (100%)     ║
║  Bugs found:       153                       ║
║  Bugs fixed:       153 / 153                 ║
║  Time:             14m 32s                   ║
║  YOUR CODEBASE IS GREEN                      ║
╚══════════════════════════════════════════════╝

Common Commands

# Full scan (all files, all languages)
qa-agent scan .

# Only scan files changed since last commit (fast re-scan)
qa-agent scan . --changed-only

# Scan specific languages only
qa-agent scan . --lang python,kotlin,java

# CI/CD mode — auto-approve patches (no prompts)
qa-agent scan . --auto-approve

# Check system health
qa-agent doctor

# Check status of a running scan
qa-agent status <job-id>

# Approve/reject a pending patch
qa-agent approve <job-id> <patch-id>
qa-agent approve <job-id> <patch-id> --reject

CI/CD Integration

GitHub Actions

name: QA Agent Scan
on: [push, pull_request]
jobs:
  qa-scan:
    runs-on: self-hosted   # needs Docker + qa-agent installed
    steps:
      - uses: actions/checkout@v4
      - name: Run QA Agent
        run: qa-agent scan . --auto-approve --output json > qa-report.json
      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: qa-report
          path: qa-report.json

GitLab CI

qa-scan:
  stage: test
  tags: [docker]
  script:
    - qa-agent scan . --auto-approve
  artifacts:
    paths: [qa-report.json]

Configuration

Create .qa-agent.env in your repo root:

# LLM Provider: ollama (local) | openai | anthropic
LLM_PROVIDER=ollama

# For cloud LLMs (faster, requires API key)
# LLM_PROVIDER=openai
# OPENAI_API_KEY=sk-...

# Models
TEST_GEN_MODEL=qwen2.5-coder:1.5b   # fast, for test generation
PATCH_MODEL=qwen2.5-coder:7b         # accurate, for bug fixing

# Scan behaviour
MAX_CHUNKS=1000                       # max functions to generate tests for
MAX_FIX_ATTEMPTS=3                    # LLM retry limit per bug

Supported Languages

How It Works (Under the Hood)

Your codebase
      │
      ▼
  qa-agent scan .
      │
   [Brain — LangGraph AI]
      │
      ├── Scan: finds all source files (git-aware, skips unchanged)
      ├── Index: tree-sitter AST → function-level chunks → Qdrant
      ├── Generate: LLM writes positive + negative + edge-case tests
      ├── Run: executes tests in isolated Docker sandbox
      ├── Heal: fixes wrong assertion values automatically
      ├── Fix: LLM analyses real bugs → proposes patches → YOU approve
      └── Report: full summary with pass rate, bugs found/fixed

Key guarantees:

• Code stays on your machine (Ollama runs locally)
• Nothing is committed without your approval
• Re-scans only process changed files (git diff)
• Known bug patterns are cached (instant fix second time)

Uninstall

# Stop and remove all containers + data
docker compose -f ~/.qa-agent/docker-compose.yml down -v

# Remove CLI
pip uninstall qa-agent

# Remove models (optional, frees ~8GB)
docker exec qa-ollama ollama rm qwen2.5-coder:7b
docker exec qa-ollama ollama rm qwen2.5-coder:1.5b

Troubleshooting

# Check all services are running
qa-agent doctor

# View logs
docker compose logs qa-brain --tail=50
docker compose logs qa-celery --tail=50

# Restart services
docker compose restart

# Common issues:
# "Ollama not responding" → docker restart qa-ollama
# "Tests not generating" → check OLLAMA_HOST in qa-app logs
# "Scan hangs" → qa-agent status <job-id> to check phase