Repository-wide guidance for pt-snap-cli, a Python 3.10+ package for importing,
splitting, and analyzing PyTorch memory snapshots. User-facing behavior belongs
in README.md, README_zh.md, and docs/; CLAUDE.md delegates here.
Read the nearest scoped guide before editing. Each guide links its children; follow the hierarchy rather than copying local rules into this file.
| Scope | Guide | Ownership |
|---|---|---|
| Package/build boundary | src | Setuptools discovery, installed assets, versioning |
| Runtime and adapters | pt_snap_cli | CLI/API, focus, Context, and subsystem routing |
| Tests | tests | Contracts, resource ownership, fixture gate, focused suites |
| Agent workflows | skills | Routing, setup, collection, diagnostics, packaged copies |
| User documentation | docs | Bilingual guides, API references, legal evidence |
| Automation | .github | Provenance guard, issue forms, CI and release |
| Performance | benchmarks | Opt-in import and SQLite measurements |
| Surface | Entry/registration | Implementation |
|---|---|---|
| Console script | pyproject.toml → pt_snap_cli.cli:_safe_call |
cli.py root commands; cli_reports.py and cli_skills.py groups; cli_output.py shared output/errors |
| Python API | api.py:SnapshotAnalyzer |
Session focus, template queries, capabilities, overview, metadata |
| Product behavior | core/ services |
Shared resolution, validation, results and errors; import/split publication; CLI-only skill management |
| Analysis | Context → query/ |
Read-only SQLite, layout detection, YAML contracts, Jinja rendering, result mapping |
| Snapshot runtime | snapshot/ via core import/split |
Trusted representation loading, allocator replay, database adaptation, slicing |
| Agent integration | Authored skills/ → packaged bundled_skills/ |
Host-loaded workflows calling the CLI; no MCP server or console entry point |
This is the canonical contributor checklist linked from both READMEs. Keep new required checks here and in the owning CI workflow rather than maintaining a shorter, divergent checklist in user onboarding docs.
Run from the repository root using the intended Python environment. Installing changes that environment and may download dependencies:
python -m pip install -e ".[dev]"For an isolated worktree using dependencies already installed elsewhere, set
PYTHONPATH="$PWD/src" on Python/test commands so imports come from that worktree.
Do not silently repoint a shared editable installation.
pytest tests/test_fixture_provenance.py # Before any committed-pickle loading
pytest # Or the owning focused suite
ruff check .
black --check .
python -m basedpyright --pythonpath "$(python -c 'import sys; print(sys.executable)')"
git diff --checkHTML interaction regressions run in a separate Chromium CI job. To run locally:
python -m playwright install chromium
PT_SNAP_REQUIRE_BROWSER=1 pytest tests/test_memory_tree_browser.pyWithout an installed browser, the ordinary suite skips these browser tests. The
required-browser flag makes missing browser support fail. PT_SNAP_TEST_CHROMIUM
may point to an existing Chromium executable instead of downloading one.
- Type checking covers all
src/pt_snap_cli, includingsnapshot/. Zero errors is the gate; warnings are informational. Preserve the file-level Any/Unknown error gates inapi.py,core/models.py, andsnapshot/representation.py; do not downgrade snapshot through anexecutionEnvironmentsexception. - Pytest treats
ResourceWarningandPytestUnraisableExceptionWarningas errors. Ownership/teardown guidance lives in tests. - Coverage is measured with branches enabled. The overall floor and independent critical-file floors are documented with CI.
bash tests/run_tests.shis an optional Bash entry point using the activepython -m pytest; setPYTHON=/path/to/pythonto choose another executable. It does not activate environments or install dependencies. Full mode retains the configured coverage floor and writes ignoredtest_reports/output;--reports-dir DIRchanges that destination.--quickomits coverage/report generation and is not a substitute for CI's full coverage gate. Use--helpfor file/keyword/marker selection and--for extra pytest arguments. Pytest's exit status is preserved, including failure and no-tests-collected. Without Bash, use the direct Python/pytest commands above..pt-snap/,.tmp/,.worktrees/, andtmp/are ignored and excluded from root Ruff/Black checks.python -m buildwritesdist/and build intermediates and may download build requirements. See packaging before using it as verification.
- One behavior layer. CLI and
SnapshotAnalyzeradapters share core semantics; updatetests/test_contract_cli_api.pywhen normalized shared results change. Skill management is CLI-only; the analyzer is not an import/split or skill-install facade. - Resolution and read-only analysis.
Config.resolve_focus()selects explicit path →PT_SNAP_DB_PATH→ nearest ancestor.pt-snap/focus.json→ legacy~/.config/pt-snap-cli/config.json. Queries select explicit device → focused device → first discovered device.Contextrequiresdictionaryand opens SQLite withmode=ro; analysis must not migrate a database or persist detected layout into focus. - Explicit resource ownership. Analyzer
close()/withends its lifetime; an injected cache stays caller-owned. Cache/service reuse and terminal analyzer closure are different contracts; see core. - Single query contract. YAML metadata, validation, registry, executor, services and adapters form one path. Layout-specific SQL shares a public schema and semantic contract. Query caps, completeness and timeouts must remain visible to callers; see query.
- Trusted input and transactional publication. Pickle loading is code execution, not a sandbox. Import stages and validates before publication and includes a requested focus update in rollback handling. Split replay-validates staged output and publishes without replacing an existing destination.
- Skill/source parity. Author
skills/<name>/SKILL.mdand keep its packagedsrc/pt_snap_cli/bundled_skills/<name>/SKILL.mdidentical. Diagnostic workflows use read-only SnapshotDB operations; setup and collection have separate mutation/consent boundaries. - Evidence and localization. Snapshot
PROVENANCE.mdis append-only; changes anywhere undersnapshot/require the PR provenance decision, including documentation-only changes. Executable fixture review is a separate acceptance process. Keep English/Chinese user guides behaviorally aligned when public behavior changes.
| Change | Start with | Verification owner |
|---|---|---|
| CLI/API, completion, focus, Context | Package adapters | Cross-surface tests |
| Cache, import/split, reports, skill destinations | Core services | Service tests |
| SQL, parameters, completeness, result semantics | Query engine, YAML templates | Query tests |
| Representation, replay, schema, slicing | Snapshot runtime | Runtime tests |
| Diagnostic instructions and evaluation | Skills | Skill contracts/harness |
| Packaging or release | Source layout, workflows | tests/test_package.py, tests/test_release_workflow.py |