Quick Start¶

Get started with SuperQode in 5 minutes.

Safety note (OSS): Run the open-source SuperQode/SuperQE in a safe, controlled environment (sandbox, VM, or low-risk machine). This reduces the blast radius for testing workflows and agent-driven actions.

Install SuperQode¶

pip install superqode

Overview¶

This guide covers:

1. Project Setup - Initialize and configure your project
2. Choose Workflow - TUI for exploration or CLI for automation
3. Connect to Agent - Set up your preferred connection mode
4. Run First QE Session - Start quality engineering

Step 1: Initialize Your Project¶

Navigate to your project and initialize SuperQode:

cd /path/to/your/project
superqe init

This will: - Create superqode.yaml in the current directory from the comprehensive role catalog - Enable core, implemented roles so you can run immediately - Leave the rest disabled so you can prune what you don’t need

Edit Configuration¶

After initialization, edit superqode.yaml to set your preferred model:

nano superqode.yaml

Choose your connection mode:

# Option 1: ACP (recommended for full features)
default:
  mode: acp
  coding_agent: opencode

# Option 2: BYOK (use your own API keys)
default:
  mode: byok
  provider: google
  model: gemini-3-pro

# Option 3: Local (privacy-first)
default:
  mode: local
  provider: ollama
  model: qwen3:8b

Step 2: Choose Your Workflow¶

SuperQode offers two workflows:

TUI (Terminal UI) - For Exploratory Testing¶

Best for: Interactive exploration, ad-hoc testing, learning

# Launch TUI
superqode

Then use TUI commands: - :connect acp opencode - Connect to agent - :qe security_tester - Switch to security role - Chat with agent: "Check for SQL injection vulnerabilities"

CLI (Command Line) - For Automation¶

Best for: CI/CD, batch processing, automation

# Run QE session directly
superqe run . --mode quick

# With specific roles
superqe run . -r security_tester -r api_tester

Step 3: Run Your First QE Session¶

Quick Scan (60 seconds)¶

For fast feedback during development:

superqe run . --mode quick

Note: QE sessions are run via CLI commands, not TUI commands. In the TUI, you interact directly with agents by typing natural language requests after switching to a QE role with :qe <role>.

Deep QE (Full Analysis)¶

For comprehensive quality analysis:

superqe run . --mode deep

Step 4: View Results¶

After a QE session completes, you'll see:

Console Output¶

╭─────────────────────────────────────────────────────╮
│                 QE Session Complete                  │
├─────────────────────────────────────────────────────┤
│ Duration: 45.2s                                      │
│ Roles Run: 3 (security_tester, api_tester, fullstack)│
│ Findings: 5 (1 critical, 2 high, 2 medium)          │
├─────────────────────────────────────────────────────┤
│ Artifacts Generated:                                 │
│   • QR: .superqode/qe-artifacts/qr/qr-2024-01-18-1a2b3c4d.json │
╰─────────────────────────────────────────────────────╯

Artifacts Location¶

All artifacts are saved to .superqode/qe-artifacts/:

.superqode/qe-artifacts/
├── manifest.json
├── qr/
│   ├── qr-<date>-<session>.json    # Quality Report (JSON)
│   └── qr-<date>-<session>.md      # Quality Report (Markdown)
├── patches/
│   └── ...                         # Suggested patch files (when available)
└── generated-tests/
    └── ...                         # Generated tests (when available)

Step 5: Essential Commands¶

TUI Commands (prefix with :)¶

CLI Commands¶

Step 6: Quick Examples¶

Example 1: Security Scan¶

# Run security-focused QE
superqe run . -r security_tester --mode quick

Example 2: API Testing¶

# Test API endpoints
superqe run . -r api_tester -r unit_tester

Example 3: Full QE with Suggestions (Enterprise)¶

# Deep QE with fix suggestions (sandbox mode)
superqe run . --mode deep --allow-suggestions --generate

Example 4: CI-Friendly Output (Enterprise)¶

# JSONL output for CI/CD
superqe run . --mode quick --jsonl

# JUnit XML for test reporting
superqe run . --mode quick --junit results.xml

Step 7: Understanding the Output¶

Finding Severity Levels¶

Confidence Scores¶

Each finding includes a confidence score (0.0 - 1.0):

• 0.9 - 1.0: Very high confidence, verified finding
• 0.7 - 0.9: High confidence, likely valid
• 0.5 - 0.7: Medium confidence, review recommended
• < 0.5: Low confidence, may be false positive

Step 8: Keyboard Shortcuts (TUI)¶

Next Steps¶

Now that you've completed the quick start:

1. Your First QE Session - Detailed walkthrough
2. Configuration Guide - Customize SuperQode
3. Understanding Modes - Learn about BYOK, ACP, Local
4. QE Roles - Understand testing roles
5. CI/CD Integration - Add to your pipeline

Tips for Success¶