CONTRIBUTING

Contributing to Cortex

Thanks for your interest. Cortex is a personal portfolio project, but patches, bug reports, and ideas are welcome.

Cortex is macOS-only. Linux and Windows are not supported and patches that add support are out of scope for the v0.2.x series.

Prerequisites

Requirement	Install
macOS 13+ (Ventura or later)	required
Python 3.11 or 3.12	brew install python@3.11
Node.js 18+	brew install node
pnpm	npm install -g pnpm
Anthropic credentials	one of: Bedrock bearer token (Keychain), GCP Vertex ADC, or ANTHROPIC_API_KEY — Cortex falls back to deterministic rule-based plans without one

One-time setup

git clone https://github.com/StevenWang-CY/cortex.git
cd cortex
make setup            # creates .venv, installs Python + pnpm deps
pip install pre-commit && pre-commit install
cp cortex/.env.example .env
python -m cortex.scripts.seed_config --root .

Common shortcuts (see Makefile):

make dev              # start the daemon
make test             # pytest
make lint             # ruff
make typecheck        # mypy --strict
make codegen          # regenerate TypeScript schema types
make codegen-check    # the CI drift gate
make ci               # everything CI runs

Schema codegen workflow

This is the project's most important convention. The Pydantic models in cortex/libs/schemas/ are the single source of truth for every shape that crosses the daemon ↔ browser-extension boundary. The generated TypeScript file at cortex/apps/browser_extension/types/generated/cortex_schemas.d.ts is hands-off:

1. Edit a Pydantic model in cortex/libs/schemas/.
2. Run make codegen to regenerate the .d.ts.
3. Commit both the Python change and the regenerated .d.ts together.
4. The pre-commit hook and the schema-codegen-check CI job both run make codegen-check, which fails the commit / PR if the .d.ts is stale.

Don't hand-edit the .d.ts. The file's header refuses it.

Adding a new WebSocket message type

1. Add a member to cortex/libs/schemas/ws_message_types.py::MessageType.
2. If the daemon dispatches on it, add a case in cortex/services/api_gateway/websocket_server.py::_process_message and update the catalog tests.
3. Run make codegen and commit the regenerated .d.ts alongside.
4. The TypeScript dispatch sites in background.ts / popup.tsx now type-check against the new union; their switch's never default flags any forgotten case at build time.

See cortex/docs/apis.md for the full message catalog.

Audit-ledger commit convention

Significant fixes that close a known issue use the audit Fxx: prefix and link the corresponding entry in audit/findings.md, e.g.:

audit F19: end-to-end correlation IDs across HTTP + WS + logs

Smaller fixes use a Conventional-Commits-flavoured prefix (docs:, meta:, devx:, test:, fix:, audit Fxx:). See git log --oneline for examples.

Pull request checklist

Before submitting:

• make ci passes locally (lint + typecheck + tests + codegen drift check)
• You added or updated tests for any code change
• If you touched a Pydantic schema, you ran make codegen and committed the regenerated .d.ts
• If your change relates to an audit finding, the commit subject starts with audit Fxx: and audit/execution-log.md is updated
• No new print() calls (use structlog via cortex.libs.logging.event)
• No biometric or webcam-frame data added to any LLM prompt path (see SECURITY.md)

What we won't merge

• Linux or Windows support (out of scope for v0.2.x — Cortex is tied to AVFoundation, TCC, and macOS-specific frameworks)
• Any change that puts biometrics into an LLM payload
• Removal of the consent ladder, undo stack, or capability-token gate
• Bypassing the schema codegen drift gate

Bug reports & ideas

Use the issue templates. For security issues, file a private security advisory instead.

License

By contributing, you agree your contribution is licensed under the MIT License.