Skip to content

docs(readme): document dev setup, local checks, and PR conventions #967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aregmii wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(readme): document dev setup, local checks, and PR conventions #967

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
36c0376
docs(readme): use markdown link for examples/hooks.py reference
aregmii May 18, 2026
32a9289
docs(readme): document dev setup, local checks, and PR conventions
aregmii May 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 36 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,7 @@ options = ClaudeAgentOptions(

A **hook** is a Python function that the Claude Code _application_ (_not_ Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Intercept and control agent behavior with hooks](https://platform.claude.com/docs/en/agent-sdk/hooks).

For more examples, see examples/hooks.py.
For more examples, see [examples/hooks.py](examples/hooks.py).

#### Example

Expand Down Expand Up @@ -289,13 +289,46 @@ If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the

## Development

If you're contributing to this project, run the initial setup script to install git hooks:
### Setting up a development environment

Install the SDK in editable mode along with the dev dependencies (`pytest`, `pytest-asyncio`, `pytest-cov`, `mypy`, `ruff`):

```bash
pip install -e ".[dev]"
```

Then install the pre-push git hook so lint checks run before each push (matching CI):

```bash
./scripts/initial-setup.sh
```

This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
To skip the hook for a single push, use `git push --no-verify`.

### Running checks locally

The pre-push hook wraps the same commands you can run directly:

```bash
# Lint and auto-fix
python -m ruff check src/ tests/ --fix

# Format
python -m ruff format src/ tests/

# Type-check
python -m mypy src/

# Tests (all)
python -m pytest tests/

# Tests (single file)
python -m pytest tests/test_client.py
```

### Pull request conventions

PR titles follow [Conventional Commits](https://www.conventionalcommits.org/), e.g. `fix(transport): handle CancelledError`, `docs: update changelog`, `feat(hooks): add SubagentStartHookInput`. Recent merged PRs are good references for tone and scope.

### Building Wheels Locally

Expand Down