v1.1.0

v1.0.0 was a list of 304 primary sources. v1.1.0 puts what those sources say inside any AI client.

cpu-perf: every source in the list, searchable and cited

The list says where to read. The MCP server holds what is there: the text of every paper, vendor manual, ISA reference, kernel and compiler document and repository the README links, indexed with page numbers. Ask a question, paste perf stat or compiler output, and the answer comes from those sources, quoting the passage and citing the page, not from a model's memory.

With uv installed, one command adds it to Claude Code:

claude mcp add --scope user cpu-perf -- uvx cpu-perf

Claude Desktop, Codex, Cursor and VS Code take a few lines of config, in misc/mcp/README.md.

What it reads:

• Every linked source, in full. On first run it fetches each link and the document behind it (the PDF behind an arXiv abstract, the manual behind a vendor landing page, a repository's README), extracts the text with page numbers, and builds a full-text and semantic index on your own machine. It refreshes as the list changes. Nothing crawled is committed or shipped.
• Everything the repository knows. Each entry and why it earns its place, in reading order; the watchlist and what would promote each item; all 541 rejected candidates with the rule each failed; the 171 numbers examined against the seven-field rule; and all fourteen benchmarks with their code, machines, raw output and analysis.

Sources that refuse automated clients (parts of the ACM, IEEE, Intel and Arm portals) are reported as blocked rather than guessed at, and the answer points to the link instead.

Published on PyPI and listed in the MCP Registry as io.github.usamahz/cpu-perf.

cpuperf.com

The list as a website, rebuilt from this repository on every merge to main: the reading path by section, the watchlist, every benchmark charted from its raw results, the full evidence record, site search, and a Markdown twin of every page with llms.txt and corpus.json for agents. Every README.md#heading link still resolves.

Checks

• MCP server: tests on Linux and Windows across Python 3.10 to 3.13, a wheel that must carry the full corpus, and a container that must serve the tools over HTTP.
• Site: checked against the README, anchors compared with GitHub's renderer, and browser tests with axe-core on every page type.
• check_format.py and check_links.py run as before.

Full Changelog: v1.0.0...v1.1.0

v1.0.0

A reading path for CPU performance engineering, from one instruction to production inference, in the order that makes the next piece legible.

304 entries across 16 sections and 60 subsections, from 288 distinct sources on 117 hosts. Primary sources only: original papers, vendor optimisation manuals and ISA references, creator repositories, kernel and compiler documentation. No blogspam, no listicles, no aggregators, no AI-generated posts. Every entry is one line saying why it earns a place, not what it is.

The evidence rule

Every performance claim carries seven fields:

1. CPU model and microarchitecture
2. core count used
3. frequency, and whether turbo and SMT were on
4. compiler and flags
5. workload
6. baseline
7. measurement method

A number missing any one of them is dropped, not softened. If the entry rests on that number it moves to the watchlist, or it goes.

This is deliberately stricter than most lists. A CPU figure quoted without its frequency, its core count or its compiler flags cannot be reproduced, and is therefore not evidence of anything.

misc/notes/changelog.md records the whole sift: 304 included, 541 rejected, 171 numbers examined, each with the rule it failed.

14 runnable benchmarks

One reproducible microbenchmark per major section, in misc/benchmarks/. Each ships bench.c, build.sh, run.sh, the machine it ran on, raw numbers and the analysis. QUICK=1 ./run.sh finishes inside ten seconds, so CI smoke tests every one of them on each push.

All fourteen ran on one machine: Apple M4 Pro, Apple clang 17.0.0, macOS 26.2, with the clock measured rather than assumed. Four of the results:

measurement	result
one dependent load, DRAM against L1	186x, with the L2 step at 8.9 and DRAM at 20.8 on top
8 threads incrementing adjacent atomics	157x slower per increment than 1 thread; padding to 128 B brings it to 1.16
one byte pread from the page cache	281 ns, about 1263 cycles
FMA loop under taskpolicy -c background	12x slower by wall time, on E-cores at 1.04 GHz

These are numbers this repository can defend, on one machine, with the method stated. They are not claims about your machine, which is the point.

What is deliberately absent

A dated watchlist of 14 items whose evidence is still moving. Each names the condition that would promote it: a specification or original paper, a shipped implementation, and a public measurement stating all seven fields. Anything failing the evidence rule lands here rather than in the list.

Checks

Two checkers run on every push, with no third-party dependency:

• check_format.py — entry grammar, reason length, numbering, watchlist promotion conditions, internal anchors, Contents completeness, duplicate URLs, empty subsections, placeholders.
• check_links.py — every URL, and again weekly on a cron. It separates dead from unreachable from blocked, because vendor document libraries and publishers refuse automated clients while serving the page perfectly well to a browser. A dead link fails the build and opens an issue.

Contributing

The bar is in CONTRIBUTING.md. Every entry has to survive one question: would someone working through the list top to bottom be worse off without it?

Full Changelog: https://github.com/usamahz/cpu-performance-engineering/commits/v1.0.0