quill: Instructions file for Claude Code

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 min vs ~9). Tests marked `machine_global` — the ones
# that drive the real clipboard, the system-wide hotkey table or the
# screen-reader bridges — share one worker; everything else fans out. Mark a
# new test that reaches for one of those, or it will race the others. The
# grouping was silently wrong twice (ignored, then too coarse to let the
# suite exit); tests/conftest.py pytest_collection_modifyitems has both
# stories and tests/unit/test_parallel_grouping.py asserts them.
#
# This is the FAST path, not the authoritative one: a worker can still die
# ("node down"), which predates the grouping and is unrelated to it. Re-run any
# failure it reports on its own before believing it -- every one so far passed
# serially. `pytest -q` is the answer that counts.
pytest -q -n 8 --dist loadgroup

# One CI shard locally (PR CI splits tests\unit + tests\accessibility four
# ways since 2026-10-11; tests/conftest.py _keep_this_shard deals whole files
# to shards). A test that runs pytest.main itself must clear QUILL_TEST_SHARD
# or its inner run deselects what it names (test_parallel_grouping.py).
$env:QUILL_TEST_SHARD = "2/4"; pytest tests\unit tests\accessibility -q -n 4 --dist loadfile

# 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