You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The README's ## Development section covers installing the pre-push git hook (scripts/initial-setup.sh) but does not document the dev-dependency install command (pip install -e ".[dev]") or the manual lint / typecheck / test commands. Those commands exist in CLAUDE.md, which is structured to guide Claude Code agents at runtime, not for human contributors who would naturally look for a CONTRIBUTING.md. Adding the missing pieces in the README or as a standalone CONTRIBUTING.md would allow external contributors to find the workflow without reverse-engineering it from merged PR history.
Steps to reproduce
Clone the repo and read README.md from top to bottom.
The ## Development section says: run scripts/initial-setup.sh to install git hooks. The hook runs "lint checks" but the manual command equivalents aren't documented.
pyproject.toml declares a dev extras group (pytest, pytest-asyncio, mypy, ruff, pytest-cov), but the install command (pip install -e ".[dev]") is not in the README.
CLAUDE.md documents the manual commands:
python -m ruff check src/ tests/ --fix
python -m ruff format src/ tests/
python -m mypy src/
python -m pytest tests/
These are not surfaced anywhere a human contributor would naturally look.
Expand the ## Development section in README.md to include the dev-deps install command, the manual lint/typecheck/test commands, and the PR title convention, OR
Add a CONTRIBUTING.md at the repo root and link it from the README's ## Development section.
Actual behavior
External contributors must read pyproject.toml (to discover the dev extras group), open CLAUDE.md (to find lint/test commands intended for Claude Code agents), and scan recent merged PRs (to infer the title format) before they can submit a clean PR.
The information already exists across the repo; the fix is to consolidate it where contributors will find it. Happy to follow up with a PR adding CONTRIBUTING.md (or expanding the Development section) once the maintainer-preferred shape is confirmed.
Short description
The README's
## Developmentsection covers installing the pre-push git hook (scripts/initial-setup.sh) but does not document the dev-dependency install command (pip install -e ".[dev]") or the manual lint / typecheck / test commands. Those commands exist inCLAUDE.md, which is structured to guide Claude Code agents at runtime, not for human contributors who would naturally look for aCONTRIBUTING.md. Adding the missing pieces in the README or as a standaloneCONTRIBUTING.mdwould allow external contributors to find the workflow without reverse-engineering it from merged PR history.Steps to reproduce
Clone the repo and read
README.mdfrom top to bottom.The
## Developmentsection says: runscripts/initial-setup.shto install git hooks. The hook runs "lint checks" but the manual command equivalents aren't documented.pyproject.tomldeclares adevextras group (pytest,pytest-asyncio,mypy,ruff,pytest-cov), but the install command (pip install -e ".[dev]") is not in the README.CLAUDE.mddocuments the manual commands:python -m ruff check src/ tests/ --fixpython -m ruff format src/ tests/python -m mypy src/python -m pytest tests/These are not surfaced anywhere a human contributor would naturally look.
PR title format (Conventional Commits) is used consistently across recent merged PRs (docs(types): clarify hooks dispatch is concurrent, not sequential #956, fix(types): tighten permission_suggestions type in SDKControlPermissionRequest #955, Export EffortLevel type alias #951, test(transcript_mirror): stabilize eager-flush tests with deterministic wait #933, fix(transport): isolate stderr callback failures, continue reading lines #932) but never documented.
Expected behavior
Either:
## Developmentsection inREADME.mdto include the dev-deps install command, the manual lint/typecheck/test commands, and the PR title convention, ORCONTRIBUTING.mdat the repo root and link it from the README's## Developmentsection.Actual behavior
External contributors must read
pyproject.toml(to discover thedevextras group), openCLAUDE.md(to find lint/test commands intended for Claude Code agents), and scan recent merged PRs (to infer the title format) before they can submit a clean PR.Environment
OS: macOS / Python: 3.12 / claude-agent-sdk: 0.2.82 (latest).
Additional context
The information already exists across the repo; the fix is to consolidate it where contributors will find it. Happy to follow up with a PR adding
CONTRIBUTING.md(or expanding the Development section) once the maintainer-preferred shape is confirmed.