permit0: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Build
cargo build --workspace
cargo build --release --workspace

# Test (CI uses nextest)
cargo nextest run --workspace
cargo test --workspace

# Run a single test
cargo nextest run -p permit0-engine <test_name>
cargo test -p permit0-scoring -- scorer::tests::more_flags_higher_score

# Lint (warnings are errors)
cargo clippy --workspace --all-targets -- -D warnings

# Format
cargo fmt --all
cargo fmt --all --check

# Supply-chain audit
cargo deny check

# Calibration tests (run after changing packs or profiles)
cargo run -- calibrate test
cargo run -- calibrate test --corpus corpora/calibration --profile fintech

# Pack testing
cargo run -- pack test packs/stripe
cargo run -- pack validate packs/stripe

# Start admin dashboard
cargo run -- serve --ui --port 9090

RUSTFLAGS="-D warnings" is set in CI; all warnings are fatal.

Python bindings (permit0-py)

The Python bindings crate is excluded from default-members, so cargo build (no flags) skips it. Two ways to build it:

# Canonical: build + install editable wheel into the active Python env
cd crates/permit0-py
maturin develop                # uses whichever Python `maturin` resolves to

# Plain cargo (also works thanks to .cargo/config.toml on macOS)
cargo build --workspace        # builds every crate including permit0-py
cargo build -p permit0-py      # builds permit0-py only

macOS notes:

• .cargo/config.toml adds -undefined dynamic_lookup for aarch64-apple-darwin and x86_64-apple-darwin so PyO3's extension-module cdylib links without a libpython.
• If both a conda env and a .venv are active, maturin refuses with a dual-env error — unset VIRTUAL_ENV (or unset CONDA_PREFIX) to disambiguate.

Architecture

permit0 is a deterministic, rule-based permission framework for AI agent tool calls. There is no LLM in the hot path — the decision pipeline is pure Rust.