qbittorrent-web: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. This file is intended for Codex, Claude, Cursor, and similar tools.

Project Snapshot

qb-web is a Vue 3 and TypeScript web UI for qBittorrent management. It targets desktop and mobile layouts, uses virtualized torrent lists for performance, and talks to the qBittorrent WebUI API through /api/v2.

• Framework: Vue 3.5 with Composition API and <script setup>
• Language: TypeScript 5.8 in strict mode
• Build: Vite through rolldown-vite
• UI: Naive UI, UnoCSS, Less
• State: Pinia setup stores
• Router: Vue Router history mode
• Package manager: pnpm >= 10
• Runtime: Node.js >= 20

First Steps For Agents

1. Read this file and the local files relevant to the task before editing.
2. Check git status --short and preserve user changes. Do not revert or rewrite unrelated files.
3. Prefer existing patterns in nearby components, stores, composables, and API modules over introducing new abstractions.
4. Keep changes scoped. Avoid broad formatting churn, dependency upgrades, or generated file edits unless the task requires them.
5. After code changes, run the narrowest meaningful verification command first, then broader checks when risk justifies it.

Commands

pnpm install
pnpm dev
pnpm check
pnpm lint
pnpm build
pnpm preview
pnpm build:prod
pnpm release:check
pnpm release

Notes:

• pnpm dev starts Vite on port 5173 and proxies /api to VITE_DOMAIN or http://localhost:8080.
• pnpm check runs vue-tsc -b.
• pnpm lint auto-fixes ESLint issues. Do not run it casually if unrelated user edits are present; inspect the diff afterward.
• pnpm build runs type checking and production build.
• There is currently no dedicated test framework configured.

Repository Layout

src/
  api/                 qBittorrent WebUI API wrappers and HTTP helpers
  api/modules/         Feature API modules such as torrents, auth, sync, rss
  components/          Reusable and feature components
  components/CanvasList/
                       High-performance torrent list and canvas renderers
  components/Settings/
                       Settings panels
  components/TorrentDetail/
                       Torrent detail tabs and context menus
  composables/         Shared Vue composition functions
  const/               Shared constants
  i18n/                Vue I18n setup and locale JSON files
  router/              Vue Router routes
  store/               Pinia setup stores
  styles/              Shared Less mixins and global styles
  utils/               Generic utilities
public/                Static public assets
scripts/               Build and release scripts
docs/                  README images and documentation assets