If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/qbittorrent/qBittorrent shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Mixed signals — read the receipts

• Last commit today
• 23+ active contributors
• Distributed ownership (top contributor 26% of recent commits)
• Other licensed
• CI configured
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live qbittorrent/qBittorrent repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/qbittorrent/qBittorrent.

What it runs against: a local clone of qbittorrent/qBittorrent — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in qbittorrent/qBittorrent | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of qbittorrent/qBittorrent. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/qbittorrent/qBittorrent.git
#   cd qBittorrent
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of qbittorrent/qBittorrent and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "qbittorrent/qBittorrent(\\.git)?\\b" \\
  && ok "origin remote is qbittorrent/qBittorrent" \\
  || miss "origin remote is not qbittorrent/qBittorrent (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"
test -f "src/base/bittorrent/session.h" \\
  && ok "src/base/bittorrent/session.h" \\
  || miss "missing critical file: src/base/bittorrent/session.h"
test -f "src/gui/mainwindow.h" \\
  && ok "src/gui/mainwindow.h" \\
  || miss "missing critical file: src/gui/mainwindow.h"
test -f "src/webui/api/apierror.h" \\
  && ok "src/webui/api/apierror.h" \\
  || miss "missing critical file: src/webui/api/apierror.h"
test -f "src/base/preferences/preferences.h" \\
  && ok "src/base/preferences/preferences.h" \\
  || miss "missing critical file: src/base/preferences/preferences.h"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/qbittorrent/qBittorrent"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

qBittorrent is a cross-platform BitTorrent client written in C++ with Qt that manages torrent downloads using the libtorrent-rasterbar library. It provides a full-featured UI (both desktop GUI and web-based), peer IP geolocation via DB-IP database, and native support for multiple operating systems (Windows, macOS, Linux) through a single codebase. Hybrid monorepo: C++ core in src/ handles BitTorrent protocol via libtorrent; Qt-based desktop GUI in src/gui/; web UI served via JavaScript/HTML/CSS in src/webui/ connected to backend via REST API (WebAPI_Changelog.md indicates versioned endpoints). CMake orchestrates multi-platform builds; platform-specific code isolated (Objective-C++ for macOS in src/app/mac/).

End users seeking a free, open-source alternative to proprietary torrent clients (Transmission, Deluge); contributors interested in C++/Qt desktop application development; system administrators needing a headless torrent server with REST API (web UI via JavaScript/HTML).

Highly mature and production-ready. The project is actively developed (evident from comprehensive CI/CD workflows across Ubuntu, macOS, Windows; Coverity static analysis integration; semantic versioning with GPG-signed releases from v3.3.4+). Large codebase (3.7M lines of C++), established community forums, and detailed coding guidelines indicate a well-maintained project used in production globally.

Low technical risk for core functionality but consider: tight coupling to libtorrent-rasterbar ABI (third-party dependency), web UI relies on custom JavaScript without mention of modern framework testing (783KB JS), single release key fingerprint (D8F3DA77AAC6741053599C136E4A2D025B7CC9A2) creates signing bottleneck. No visible package.json suggests web UI testing may be minimal compared to C++ test coverage.

Active CI/CD maturation visible: separate workflows for ci_ubuntu.yaml, ci_macos.yaml, ci_windows.yaml, ci_webui.yaml, CodeQL security scanning, Python testing (ci_python.yaml), and Coverity integration. Pre-commit hooks configured (.pre-commit-config.yaml) with typo checking and translation validation. Dependabot enabled for dependency management.

git clone https://github.com/qbittorrent/qBittorrent.git
cd qBittorrent
mkdir build && cd build
cmake ..
make -j$(nproc)
make install

Refer to INSTALL file for OS-specific dependencies (Qt, libtorrent-rasterbar, OpenSSL, zlib).

Daily commands: Desktop: After build, run ./qbittorrent (GUI) or ./qbittorrent-nox (headless). Headless accesses web UI at http://localhost:8080 by default. Web UI development requires no separate server—served by C++ backend on port 8080.

• CMakeLists.txt — Primary build configuration that defines the entire project structure, dependencies, and compilation for all platforms; essential for understanding the build system.
• src/base/bittorrent/session.h — Core BitTorrent session management using libtorrent; fundamental to understanding torrent lifecycle and peer management.
• src/gui/mainwindow.h — Main GUI entry point that orchestrates the desktop UI; critical for understanding the application's user-facing architecture.
• src/webui/api/apierror.h — Web API framework and error handling; essential for REST API consumers and developers extending API endpoints.
• src/base/preferences/preferences.h — Configuration management and persistent settings; required for understanding how preferences flow through the application.
• src/base/logger.h — Application-wide logging infrastructure; critical for debugging and understanding application flow.
• CONTRIBUTING.md — Contribution guidelines and coding standards specific to this project; mandatory reading for any developer submitting changes.

Add a new Web API endpoint

1. Create a new controller class inheriting from ApiController in src/webui/api/ (src/webui/api/yourcontroller.h)
2. Define GET/POST handler methods with proper ApiError checking (src/webui/api/yourcontroller.cpp)
3. Register the new controller in src/webui/webapplication.cpp route mapping (src/webui/webapplication.cpp)
4. Update WebAPI_Changelog.md documenting the new endpoint (WebAPI_Changelog.md)

Add a new preference setting

1. Add property to the Preferences class with getter/setter in src/base/preferences/ (src/base/preferences/preferences.h)
2. Implement storage using the internal SettingValue mechanism in preferences.cpp (src/base/preferences/preferences.cpp)
3. Add GUI control to preferences dialog in src/gui/options/ (src/gui/options/optionswidget.h)

Add a new torrent filter or column

1. Define filter logic in src/base/bittorrent/torrentfilter.h or extend Torrent class (src/base/bittorrent/torrentfilter.h)
2. Update the transfer list model in src/gui/transferlistmodel.h to expose new data (src/gui/transferlistmodel.h)
3. Add column header and sorting in src/gui/transferlistwidget.h (src/gui/transferlistwidget.h)

Extend BitTorrent session functionality

1. Add method to BitTorrentSession in src/base/bittorrent/session.h (src/base/bittorrent/session.h)
2. Implement using libtorrent APIs in session.cpp with proper error handling (src/base/bittorrent/session.cpp)
3. Emit signals for state changes to notify GUI and API consumers (src/base/bittorrent/session.h)

• C++ with Qt — Provides cross-platform GUI and high-performance networking; Qt enables native UI on Windows, macOS, and Linux with minimal code duplication.
• Libtorrent (libtorrent-rasterbar) — Industry-standard, well-maintained C++ BitTorrent library handling protocol complexity, peer management, and torrent I/O.
• CMake — Cross-platform build system supporting conditional compilation for different operating systems and optional features.
• RESTful HTTP API with Qt server — Enables remote control via Web UI and third-party integrations without requiring an external server framework.

• Single-process architecture with Qt event loop

  • Why: Simplifies state management and GUI synchronization
  • Consequence: Heavy CPU operations (e.g., torrent creation, large file operations) can briefly freeze UI; mitigated by threading in critical paths.

• Embedded Web API instead of separate microservice

  • Why: Reduces deployment complexity and allows tight integration with core session state
  • Consequence: Web API and desktop GUI compete for resources on the same process; no horizontal scaling of API.

• SQLite-style preferences file instead of distributed config

  • Why: Single-user desktop application philosophy; simplifies installation and portability
  • Consequence: Not suitable for multi-user server deployments without additional architecture.

• Libtorrent async I/O with Qt signals for GUI updates

  • Why: Leverages Qt's mature signal/slot threading model and event-driven architecture
  • Consequence: Requires careful threading discipline; blocking calls in GUI thread can freeze interface.

• Multi-user authentication and authorization (single-user desktop app + optional API authentication)
• Real-time collaborative features (focused on local torrent management)
• Server-side clustering or horizontal scaling
• Mobile app (desktop-only; Web UI is remote control, not mobile-optimized)
• Blockchain or decentralized features (standard BitTorrent protocol only)

1. Qt version compatibility: Project supports both Qt 5 and Qt 6; CMake auto-detects but some UI files (.ui XML) may not be backward-compatible—check CONTRIBUTING.md for supported versions. 2. libtorrent-rasterbar ABI coupling: Uses C++ ABI directly; upgrading libtorrent may require rebuild and API adjustments in src/base/bittorrent/. 3. Web UI must be rebuilt: JavaScript in src/webui/ is not minified by default; development vs. production builds have different paths (check src/webui/CMakeLists.txt). 4. Platform-specific secrets: macOS code signing requires Apple certificate in CI; Windows needs MSVC toolchain. 5. Transifex integration: Translations flow via .tx/config; modifying translation keys without Transifex sync breaks i18n pipeline.

• BitTorrent Protocol (DHT, PEX, Magnet Links) — Core to qBittorrent's function; src/base/bittorrent/ implements these via libtorrent, and understanding DHT peer discovery vs. tracker communication is critical for debugging connectivity issues
• Qt Signals/Slots Event Model — qBittorrent's threading and UI update mechanism relies entirely on Qt's signal/slot system; misunderstanding thread affinity causes crashes and race conditions in GUI code
• REST API Versioning (WebAPI) — qBittorrent maintains a versioned REST API (see WebAPI_Changelog.md) for backward compatibility; changes to src/webui/ endpoints must follow semantic versioning to avoid breaking remote clients
• Memory-Mapped I/O for Torrent Files — libtorrent uses mmap for efficient torrent data access on disk; understanding mmap behavior on Windows vs. POSIX systems explains platform-specific I/O performance and locking issues
• CMake Multi-Platform Build Orchestration — qBittorrent's CMakeLists.txt and cmake/Modules/ enable single-source builds for Windows (MSVC), macOS (Clang), and Linux (GCC); misconfigurations cause platform-specific build failures in CI
• Cross-Platform File I/O and Path Handling — qBittorrent uses Qt's QFile and QDir abstractions to handle Windows vs. POSIX path separators and permissions; improper path handling causes silent failures on specific platforms
• Libtorrent Session Management (Rate Limiting, DHT Bootstrap) — src/base/bittorrent/session.cpp manages a single global libtorrent session with bandwidth throttling, port mapping, and DHT initialization; incorrect session settings degrade performance for all torrents

• arvidn/libtorrent — The core BitTorrent protocol library that qBittorrent wraps; understanding libtorrent's session/torrent/peer APIs is essential for src/base/bittorrent/ changes
• transmission/transmission — Direct competitor in cross-platform torrent clients; useful reference for feature parity (magnet links, RSS, remote UI) and architectural trade-offs
• deluge/deluge — Alternative Python-based torrent client with plugin architecture; relevant for REST API design patterns and headless/remote client patterns that qBittorrent emulates
• Qt/qtbase — Qt framework source; essential when debugging widget behavior, signal/slot issues, or platform-specific Qt builds (especially Qt 6 migration)
• qbittorrent/qBittorrent-Enhanced-Edition — Community fork extending qBittorrent with additional features (IP filtering, plugin system); useful to see how others extend the codebase without upstreaming

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add CodeQL security scanning workflow for Python dependencies

The repo has a CodeQL workflow helper directory (.github/workflows/helper/codeql/) with cpp.yaml and js.yaml, but no Python configuration. Given that qBittorrent uses Python for CI helpers (check_grid_items_order.py, check_translation_tag.py) and has a ci_python.yaml workflow, adding Python-specific CodeQL scanning would detect security vulnerabilities in these automation scripts and any future Python dependencies.

• [ ] Review existing .github/workflows/helper/codeql/cpp.yaml and js.yaml structure
• [ ] Create .github/workflows/helper/codeql/python.yaml with appropriate language configuration
• [ ] Reference it in .github/workflows/codeql-scan.yaml (if exists) or create integration
• [ ] Test the workflow runs successfully on a test branch
• [ ] Document Python security scanning in CONTRIBUTING.md

Implement pre-commit hook validation for CMake build system consistency

The repo has .pre-commit-config.yaml and a pre-commit helper directory (.github/workflows/helper/pre-commit/) with custom checks, but no CMake linting/validation. With multiple CMakeLists.txt files (root, dist/, dist/mac/, dist/unix/) and cmake/Modules/, adding cmake-format or cmake-lint validation would catch build configuration inconsistencies before merge and maintain consistency across the complex build system.

• [ ] Review existing checks in .github/workflows/helper/pre-commit/ (typos, translation_tag, grid_items_order)
• [ ] Create .github/workflows/helper/pre-commit/check_cmake_format.py to validate CMakeLists.txt files
• [ ] Add cmake-format configuration or cmake-lint rules
• [ ] Update .pre-commit-config.yaml to include the new CMake check
• [ ] Document the new check in CONTRIBUTING.md or CODING_GUIDELINES.md

Add WebUI integration tests in ci_webui.yaml workflow

The repo has a dedicated .github/workflows/ci_webui.yaml workflow and WebAPI_Changelog.md, indicating an active WebUI component, but there's no visible test suite configuration for WebUI-specific functionality (e.g., API endpoint validation, UI component rendering). Adding structured WebUI integration tests would catch API/UI regressions and ensure the WebAPI changelog stays synchronized with actual behavior.

• [ ] Identify WebUI source code location (likely in src/ or a dedicated webui/ directory not shown in partial structure)
• [ ] Create a test suite for WebUI endpoints (if not already present) or identify existing test patterns
• [ ] Enhance .github/workflows/ci_webui.yaml to run WebUI integration tests (API requests, response validation)
• [ ] Add test coverage reporting for WebUI components
• [ ] Document WebUI testing approach in CONTRIBUTING.md alongside existing ci_python.yaml and ci_ubuntu.yaml examples

• Add unit tests for src/webui/api/ endpoints: REST API handlers lack dedicated test coverage visible in file list; create pytest fixtures in .github/workflows/ci_python.yaml referencing to validate HTTP responses and edge cases.
• Improve clang-tidy compliance: .clang-tidy exists but is often ignored; audit src/gui/ for modern C++ idioms (e.g., replace raw pointers with std::unique_ptr), document suppressions, and add pre-commit check in .pre-commit-config.yaml.
• Enhance web UI accessibility: src/webui/ JavaScript lacks ARIA labels and keyboard navigation; audit HTML files against WCAG 2.1 AA standard, add role attributes, and test with screen readers to improve usability for visually impaired users.

qBittorrent demonstrates reasonable security practices with security reporting guidelines, static analysis tools configured, and active CI/CD workflows. However, the analysis is limited by incomplete visibility into actual code, dependency specifications, and workflow configurations. Key observations: (1) Security policy exists but is incomplete; (2) No obvious hardcoded secrets detected; (3) Build pipeline and dependency management practices require verification; (4) Third-party database attribution requirements must be maintained. Recommend: complete SECURITY.md, verify CI/CD pipeline security, implement strict dependency version management, and perform comprehensive code review focusing on network input handling (BitTorrent protocol), file operations, and WebAPI security.

• Medium · Missing SECURITY.md Details — SECURITY.md. The SECURITY.md file is incomplete and truncated. It doesn't fully describe the security reporting process or provide complete contact information for security researchers. Fix: Complete the SECURITY.md file with full security reporting guidelines, response timelines, and complete contact information.
• Low · Potential Dependency Management Risk — CMakeLists.txt, cmake/Modules/. No package lock files or dependency version specifications are visible in the provided file structure. While CMakeLists.txt is present, explicit dependency version pinning is not evident. Fix: Implement strict version pinning for all dependencies and maintain a lock file. Regularly audit dependencies using tools like OWASP Dependency-Check or Snyk.
• Low · Third-Party Database with Attribution Requirements — README.md, documentation. The project uses the DB-IP IP-to-Country Lite database which requires Creative Commons Attribution 4.0 compliance. Ensure proper attribution is maintained in distributions. Fix: Verify that all distribution packages include proper attribution to DB-IP and maintain compliance with CC-BY 4.0 license requirements.
• Low · Limited Visibility into Build Security — .github/workflows/. Multiple GitHub Actions workflows are present (.github/workflows/) but their contents are not fully visible. CI/CD pipeline security should be verified. Fix: Review all CI/CD workflows for: proper secret management, signed commits, artifact verification, and supply chain security practices.
• Low · Clang-Tidy Configuration Present — .clang-tidy. While .clang-tidy exists (good practice), its configuration content is not visible. Static analysis rules should be properly configured. Fix: Verify that clang-tidy is configured with strict security checks. Enable checks for memory safety, integer overflow, and common vulnerability patterns.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.