cocoindex: Instructions file for Codex

AGENTS.md

This file provides guidance to coding agents working with code in this repository. Claude Code compatibility is kept through CLAUDE.md, which imports this file.

Build and Test Commands

This project uses uv for Python project management.

Building

uv run maturin develop   # Build Rust code and install Python package (required after Rust changes)

Testing

cargo test               # Run Rust tests
uv run mypy              # Type check Python code
uv run pytest python/    # Run Python tests (use after both Rust and Python changes)

Code Formatting and Linting

Python linting and formatting go through prek, which runs the ruff-check and ruff-format hooks from .pre-commit-config.yaml with the exact ruff version and file set CI uses. A ruff from uv run, uvx, or Homebrew is usually a different version than the hook pins, so run the hooks rather than ruff itself.

uv tool install prek                         # one-time; some hooks also need `protoc` (brew install protobuf)
prek run ruff-check ruff-format --all-files  # Lint (applying safe fixes), then format Python code (same as CI)
cargo fmt                                    # Format Rust code
./dev/run_cargo_clippy.sh                    # Lint Rust code other than the Rust SDK and its CLI (same as CI)
./dev/run_cargo_clippy_sdk.sh                # Lint the Rust SDK and its CLI, `rust/cli` (same as CI)

Pre-submission Checks

CI enforces the full pre-commit hook suite from .pre-commit-config.yaml, which covers more than the commands above — notably regenerating the CLI docs (docs/src/content/docs/cli.mdx) whenever cli.py changes. Before pushing, run the hooks whose inputs your branch changed, as PR CI does:

prek run --from-ref origin/main --to-ref HEAD

prek run --all-files runs every hook on every file, the Rust SDK hooks (cargo-test-sdk, cargo-clippy-sdk, cargo-test-rust-externs) included. The Rust SDK isn't launched yet, so those hooks run only for a change under rust/sdk/, rust/cli/, examples/rust/ or benchmarks/*/rust/, not for a change to the code the SDK builds on. The Rust SDK Daily workflow runs them on main every day and files an issue when they fail.