Contributing

Local Setup

Kolega Code requires Python 3.11 or newer.

Install the CLI, development dependencies, and the tracked Git hooks with the setup script:

./scripts/setup-dev.sh

If you prefer to run the steps manually:

uv sync --extra cli --extra dev
git config core.hooksPath .githooks
uv run pre-commit install-hooks
uv run pre-commit run --all-files --show-diff-on-failure

Installing the pre-commit Python package is not enough. This repository uses a tracked .githooks/pre-commit wrapper that runs the exact same all-files command as CI. Run ./scripts/setup-dev.sh or git config core.hooksPath .githooks once per clone.

If you prefer pip, install the package in editable mode:

pip install -e ".[cli,dev]"

Run the CLI locally:

kolega-code .

Some slow and integration tests require provider credentials. Copy the example environment file only when you need those tests, and never commit real secrets:

cp .env.example .env

Tests and quality checks

Verify that Git is configured to use the tracked hooks:

./scripts/check-dev-hooks.sh

Local commits run the same all-files pre-commit command as CI when core.hooksPath points to .githooks:

uv run pre-commit run --all-files --show-diff-on-failure

CI runs Ruff and Pyright through pre-commit. You can also run them directly for one-off checks:

uv run ruff check .
uv run ruff format --check .
uv run pyright

To apply formatting locally:

uv run ruff format .

Type checking

The project uses Pyright in basic mode to catch type errors before runtime. The configuration lives in [tool.pyright] in pyproject.toml.

Run the type checker locally:

uv run pyright

Guidelines for type annotations:

• All new code should have type annotations on function signatures and class attributes.
• Use # pyright: ignore[<rule>] sparingly and only for third-party stub limitations — never to silence errors in first-party code.
• Prefer narrowing Optional values with assert or if guards over ignoring the error.

Run the fast test suite before opening a pull request:

./run_tests.sh

The wrapper runs tests in parallel using the available CPU cores. Set PYTEST_WORKERS to cap concurrency, or set it to 0 for a serial debugging run:

PYTEST_WORKERS=4 ./run_tests.sh
PYTEST_WORKERS=0 ./run_tests.sh tests/test_git_env.py

Run slow and integration tests only when you have the required credentials:

./run_tests.sh --all

You can pass additional pytest arguments through the wrapper:

./run_tests.sh tests/test_git_env.py -ra

Updating bundled skills

Kolega Code vendors a reviewed, tagged snapshot from kolega-ai/kolega-skills. It never downloads skills while building, installing, or running.

To update the snapshot, create or choose an immutable upstream tag and run:

uv run python scripts/sync_bundled_skills.py ../kolega-skills --tag vX.Y.Z

The script exports the tag's Git object rather than the sibling working tree, replaces kolega_code/_bundled_skills/ atomically, and records the tag, commit, file list, and SHA-256 hashes in manifest.json. Review all generated changes, then verify the distributions:

uv build
uv run python scripts/verify_bundled_skill_artifacts.py dist/*

Always pin an explicit tag. Do not vendor a branch, a moving latest reference, or uncommitted files from the upstream checkout.

Documentation

The documentation site lives in docs/.

cd docs
npm ci
npm run build

Use npm run dev from docs/ for local documentation development.

Maintainer automation

The CI workflow updates docs/src/assets/coverage.svg by opening an automated pull request. Configure the repository secret COVERAGE_BADGE_PR_TOKEN with a trusted bot or maintainer token instead of GITHUB_TOKEN; GitHub requires manual approval before workflows run on pull requests opened by github-actions[bot].

Use a fine-grained personal access token or GitHub App token scoped to this repository with:

• Contents: read and write
• Pull requests: read and write
• Metadata: read-only, included automatically

The token owner should be a trusted repository member or bot account. Do not use a first-time external contributor account, and never commit the token value.

Optional repository variables can customize the Git commit identity used for the badge update commit:

• COVERAGE_BADGE_AUTHOR
• COVERAGE_BADGE_COMMITTER

Use values like Name <email@example.com>.

Pull Requests

• Keep changes focused and avoid unrelated refactors.
• Add or update tests for behavior changes.
• Update documentation when user-facing behavior changes.
• Do not commit .env, local settings, credentials, API keys, tokens, or private endpoints.
• Use obviously fake credential placeholders in tests and docs, not strings that match real token formats.
• Report security issues privately according to SECURITY.md.