quill CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Install
pip install -e ".[ui,dev]"

# Install, fast (uv resolves/installs the same extras in seconds; dev-only
# tooling — releases still build with pip + the pinned system Python)
uv pip install -e ".[ui,dev]"

# Run the app
python -m quill

# Tests (standard)
pytest -q

# Tests, parallel (~5.5 min vs ~9; wx/UI tests stay on one worker — see
# tests/conftest.py pytest_collection_modifyitems for why loadgroup)
pytest -q -n 8 --dist loadgroup

# Fast smoke subset (high-signal core checks; seconds, not minutes)
pytest -m smoke -q

# Single test
pytest tests/unit/core/test_paths.py -x -q

# Run unit + stability
pytest tests/unit/ tests/stability/ -q

# Lint
ruff check .
ruff format --check .

# Scoped type-check (always scoped — never run unscoped mypy)
mypy quill\core quill\io

# Quillin self-lint
python -m quill.tools.quillin_lint <dir> --strict

# Agent standards lint (default: bundled agents dir; pass a path to lint one)
python -m quill.tools.agent_lint quill/core/ai/agents --strict

# Every gate at once, as one accessible scorecard (exit != 0 on any failure)
python -m quill.tools.platform_report

# App icons (regenerate all; --check fails on drift, --preview writes 256/16 PNGs)
python scripts/build_app_icons.py

The tests/conftest.py fixture sets quill.core.paths._DEV_BUILD = True for the whole test session. Any test that sets QUILL_DATA_DIR for isolation depends on this; do not remove it.

Architecture

QUILL is a layered wxPython desktop application with strict import boundaries:

• quill/core — pure domain logic (documents, command registry, settings, keymap, storage, AI sessions, recovery). No wx imports. Strict-typed; always in scope for mypy.
• quill/io — format readers/writers (read(path) -> Document, write(doc, path)). No wx. Strict-typed.
• quill/ui — wxPython shell. main_frame.py is the primary entry point (~27k lines and still the largest module by far); decomposition into feature mixins (see main_frame_vault.py, main_frame_speech.py, main_frame_braille.py, etc.) is the preferred home for new command handlers — add to a mixin, not to main_frame.py. Gradual typing (excluded from mypy).
• quill/platform/windows — Windows-specific bridges: prism_bridge.py (screen-reader announcements via Prism/pyttsx3), sr_detect.py, dpapi.py, credential_manager.py.
• quill/stability — cross-cutting runtime safety: safe_subprocess.py, crash_report.py (diagnostic bundles), redaction.py (secret scrubbing), task_manager.py, wx_heartbeat.py, safe_mode.py.
• quill/tools — internal CI gates: check_banned_patterns.py, module_size_budget.py, network_egress_audit.py, dialog_inventory.py, dialog_button_contract.py, quillin_lint.py, error_code_audit.py.
• quill/plugins — plugin-facing API surfaces and Quillin (extension) manifest model.