nox-mcp: Instructions file for Codex

AGENTS.md

This file provides essential project information and development standards for coding agents working on the nox-mcp project.

Project Overview

nox-mcp is a Python application for creating AI generated commit messages based on code changes.

• Repository: https://github.com/rvforest/nox-mcp
• Documentation: https://nox-mcp.readthedocs.io
• License: MIT
• Python Version: 3.10+
• Main Dependencies: No runtime dependencies by default. Development and documentation dependencies are defined in pyproject.toml (dev: Ruff, pyrefly, pytest, pytest-cov, pre-commit, nox; docs: Sphinx, myst-parser, furo, sphinx-autodoc2)

Architecture Overview

The project is organized into several core components:

Directory Structure

The project follows a standard layout:

• src/nox_mcp/ — package source
• tests/ — test suite mirroring the src/ structure
• docs/ — documentation source and build files
• noxfile.py — nox sessions for running tests, docs, linting, and other tasks
• .github/ — CI workflows
• .pre-commit-config.yaml — local pre-commit hooks configuration

Development Standards

Development Environment Setup

1. Prerequisites: Python 3.10+, Git, uv package manager
2. Setup: Run uv sync to create virtual environment and install dependencies
3. Workflow: Create feature branches, make changes, test, commit, and open PRs

Code Quality Standards

Code Style and Formatting

• Tool: Ruff (Black-compatible formatting + linting)
• Commands:
  • Format code: uv run nox -s format
  • Check linting: uv run nox -s lint
  • Check all: uv run nox -s check

Type Hints

• Required: All public functions, classes, and methods must have type hints
• Tool: pyrefly for static type checking
• Command: uv run nox -s types

Documentation

• Style: Google-style docstrings for all public APIs
• Tool: Sphinx with autodoc2, myst_parser extensions
• Commands:
  • Build docs: uv run nox -s docs
  • Live docs: uv run nox -s livedocs
• Include usage examples in docstrings where applicable.