CLAUDE.md in modular/modular runs 1,144 words across 45 headings.
The Modular Platform (includes MAX & Mojo)
MojoCovers
12 of the 20 section tags
In the order a file is read inHeadings
45 headings, in the order the file writes them
01Development Guidelines
02Repository Overview
03Essential Build Commands
04Global Build System (Bazel)
05Build everything
06Build specific targets
07Run tests
08Find targets
09Pixi Environment Management
10Install Pixi environment (run once per directory)
11Run Mojo files through Pixi
12Format Mojo code
13Use predefined tasks from pixi.toml
14Common Pixi tasks available in different directories:
15- /mojo/: build, tests, examples, benchmarks
16- /max/examples/*/: main, test, hello, dev-server, format
17- /mojo/examples/*/: main, test, hello, dev-server, format
18List available tasks
19MAX Server Commands
20Install the MAX nightly within a Python virtual environment using pip
21Install MAX globally using Pixi, an alternative to the above
22Start OpenAI-compatible server
23Run with Docker
24High-Level Architecture
25Repository Structure
26Key Architectural Patterns
27Development Workflow
28Branch Strategy
29Testing Requirements
30Run tests before committing
31Run with sanitizers
32Multiple test runs
33Code Style
34Performance Development
35Run benchmarks with compile-time defines
36Use autotune tools
37Critical Development Notes
38Mojo Development
39MAX Kernel Development
40Common Pitfalls
41Compile-Time Defines
42Contributing Areas
43Platform Support
44LLM-friendly documentation
45Git commit style
Commands
5 commands this file writes down
Extracted from the file, verbatimpip install "max[serve]" --extra-index-url https://whl.modular.com/nightly/simple/
docker run --gpus=1 -p 8000:8000 docker.modular.com/modular/max-nvidia-full:latest --model modularai/Llama-3.1-8B-Instruct-GGUF
python max/kernels/benchmarks/autotune/kbench.py benchmarks/gpu/linalg/bench_matmul.yaml
git commit -s
git log --oneline -50 -- path/to/component
The file
CLAUDE.md
First 160 of 275 lines1# Development Guidelines
2
3This file provides guidelines for AI coding assistants such as Claude Code when
4working with code in this repository.
5
6## Repository Overview
7
8The Modular Platform is a unified platform for AI development and deployment
9that includes:
10
11- **MAX**: High-performance inference server with OpenAI-compatible endpoints
12for LLMs and AI models
13- **Mojo**: A new programming language that bridges Python and systems
14programming, optimized for AI workloads
15
16## Essential Build Commands
17
18### Global Build System (Bazel)
19
20All builds use the `./bazelw` wrapper from the repository root:
21
22```bash
23# Build everything
24./bazelw build //...
25
26# Build specific targets
27./bazelw build //max/kernels/...
28./bazelw build //mojo/stdlib/...
29
30# Run tests
31./bazelw test //...
32./bazelw test //max/kernels/test/linalg:test_matmul
33
34# Find targets
35./bazelw query '//max/...'
36./bazelw query 'tests(//...)'
37```
38
39### Pixi Environment Management
40
41Many directories include `pixi.toml` files for environment management. Use Pixi
42when present:
43
44```bash
45# Install Pixi environment (run once per directory)
46pixi install
47
48# Run Mojo files through Pixi
49pixi run mojo [file.mojo]
50
51# Format Mojo code
52pixi run mojo format ./
53
54# Use predefined tasks from pixi.toml
55pixi run main # Run main example
56pixi run test # Run tests
57pixi run hello # Run hello.mojo
58
59# Common Pixi tasks available in different directories:
60# - /mojo/: build, tests, examples, benchmarks
61# - /max/examples/*/: main, test, hello, dev-server, format
62# - /mojo/examples/*/: main, test, hello, dev-server, format
63
64# List available tasks
65pixi task list
66```
67
68### MAX Server Commands
69
70```bash
71# Install the MAX nightly within a Python virtual environment using pip
72pip install "max[serve]" --extra-index-url https://whl.modular.com/nightly/simple/
73
74# Install MAX globally using Pixi, an alternative to the above
75pixi global install max-serve -c conda-forge -c https://conda.modular.com/max-nightly
76
77# Start OpenAI-compatible server
78max serve --model modularai/Llama-3.1-8B-Instruct-GGUF
79
80# Run with Docker
81docker run --gpus=1 -p 8000:8000 docker.modular.com/modular/max-nvidia-full:latest --model modularai/Llama-3.1-8B-Instruct-GGUF
82```
83
84## High-Level Architecture
85
86### Repository Structure
87
88```text
89modular/
90├── mojo/ # Mojo programming language
91│ ├── stdlib/ # Standard library implementation
92│ ├── docs/ # User documentation (mojolang.org)
93│ ├── proposals/ # Language proposals (RFCs)
94│ ├── examples/ # Mojo usage examples
95│ └── integration-test/ # Integration tests
96├── max/ # MAX framework
97│ ├── kernels/ # High-performance Mojo kernels (GPU/CPU)
98│ ├── mojo/max/ # The `max` Mojo package
99│ │ ├── gpu/ # GPU programming APIs (`max.gpu`)
100│ │ ├── algorithm/ # Parallel algorithms (`max.algorithm`)
101│ │ ├── benchmark/ # Benchmarking tools (`max.benchmark`)
102│ │ └── runtime/ # Async runtime APIs (`max.runtime`)
103│ ├── python/max/ # Python packages
104│ │ ├── serve/ # Inference server (OpenAI-compatible)
105│ │ ├── pipelines/ # Model architectures (Python)
106│ │ ├── nn/ # Neural network operators (Python)
107│ │ ├── driver/ # Device and runtime driver
108│ │ └── ... # graph, engine, kv_cache, etc.
109│ ├── examples/ # MAX usage examples
110│ └── tests/ # MAX tests
111├── docs/ # MAX docs site sources (max.modular.com)
112└── bazel/ # Build system configuration
113```
114
115### Key Architectural Patterns
116
1171. **Language Separation**:
118 - Low-level performance kernels in Mojo (`max/kernels/`)
119 - High-level orchestration in Python (`max/python/max/serve/`,
120 `max/python/max/pipelines/`)
121
1222. **Hardware Abstraction**:
123 - Platform-specific optimizations via dispatch tables
124 - Support for NVIDIA/AMD GPUs, Intel/Apple CPUs
125 - Device-agnostic APIs with hardware-specific implementations
126
1273. **Memory Management**:
128 - Device contexts for GPU memory management
129 - Host/Device buffer abstractions
130 - Careful lifetime management in Mojo code
131
1324. **Testing Philosophy**:
133 - Tests mirror source structure
134 - Use `lit` tool with FileCheck validation
135 - Hardware-specific test configurations
136 - Migrating to `testing` module assertions
137
138## Development Workflow
139
140### Branch Strategy
141
142- Work from `main` branch (synced with nightly builds)
143- Released versions live on per-release branches named `max/v<version>`, cut
144 from `main`
145- Create feature branches for significant changes
146
147### Testing Requirements
148
149```bash
150# Run tests before committing
151./bazelw test //path/to/your:target
152
153# Run with sanitizers
154./bazelw test --config=asan //...
155
156# Multiple test runs
157./bazelw test --runs_per_test=10 //...
158```
159
160### Code Style
115 more lines are in the file. Read the raw file.
The rest of the repository
modular/modular ships 8 other instruction files
max/kernels/CLAUDE.md.cursor/rules/general_behavior_rules.mdc.cursor/rules/git.mdc.cursor/rules/max_development.mdc.cursor/rules/mojo.mdcmax/CLAUDE.mdmax/tests/tests/graph/ops/.cursor/rules/ops-testing.mdcmojo/CLAUDE.md
A row that is not a link is a file this repository ships that this app did not freeze a sheet for. It is listed because the corpus knows it exists, and it is not linked because there is nothing here to open.
This listing
Whoever runs modular/modular can claim it
This is yours? Claim this config and we will write to you when the measurement moves. The check is one token placed where only you can place it, and there is no account and no password.