Install Instructions#

You can either install through PyPI:

pip install compileiq

Or, build from the repo yourself:

pip install -e .

Supported Platforms#

CompileIQ supports Python 3.11, 3.12, and 3.13. Published wheels include the bundled CompileIQ core for:

Linux x86_64
Linux aarch64
Windows amd64

Linux wheels target glibc 2.34 or newer and are tagged manylinux_2_34. macOS is not currently a packaged-core target.

Runtime Requirements#

On Linux, the bundled core expects the platform C/C++ runtime libraries and zlib to be available on the host. Package names vary by distribution; on Debian/Ubuntu, the direct runtime packages for the current Linux wheels are:

sudo apt-get update
sudo apt-get install -y \
  libc6 \
  libgcc-s1 \
  libstdc++6 \
  zlib1g

On Windows, install the Microsoft Visual C++ Redistributable 2015 or newer (x64) if it is not already present.

Managing Searches with Coding Agents#

CompileIQ ships an agent-agnostic skill set under agent-skills/ that any AGENTS.md-aware coding agent (Claude Code, Codex, Cursor, GitHub Copilot, Aider, Windsurf) can use to drive optimization campaigns. The skills follow the agentskills.io SKILL.md convention.

Skill	Use when
`compileiq-bootstrap`	First-time setup, socket timeout, or before any other skill
`compileiq-booster-pack`	Try a curated ACF candidate before paying for a full search
`compileiq-search-space`	Choosing a provider class or pinning a search-space release (incl. the `att` variant for attention workloads)
`compileiq-author-objective`	Writing or fixing the function passed as `objective_function=`
`compileiq-run-search`	Composing `Search(...)` and calling `.start()`
`compileiq-validate-result`	Validating a winning ACF with Welch’s t-test before shipping
`compileiq-debug`	Any unexpected behavior; symptom-indexed table

Install for your agent of choice (auto-detects available agents if --agents is omitted):

bash agent-skills/install.sh                          # auto-detect
bash agent-skills/install.sh --agents claude-code,codex,cursor,copilot
bash agent-skills/install.sh --check                   # verify
bash agent-skills/install.sh --uninstall               # remove mounts

Recommended order for a fresh project: bootstrap → booster-pack → (only if no pack helps) author-objective → run-search → validate-result, with debug available throughout. See agent-skills/README.md for the full layout and authoring conventions.

Environment Configuration Options#

Environment Variable	Default Value	Type	Description
CIQ_SOCKET_TIMEOUT	20	int	Controls how long CompileIQ waits for a core response. If you experience timeouts because your search space is too big, consider increasing this value.
CIQ_KEEP_CACHE	False	bool	If set to True, `.cache` files will not be deleted.
CIQ_PROCESS_MODE	“forkserver”	str	User can set this to “fork” to better separate processes and deal with threads. `IsoMultiProcessWorker` uses `fork` as the default.
CIQ_SEARCH_SPACES_DIR	unset	path	Reads compiler search-space `manifest.json` and `.bin` files from a local mirror instead of GitHub.
CIQ_SEARCH_SPACES_REPO	NVIDIA/CompileIQ	str	GitHub repository used for search-space release lookups, useful for staging or a future dedicated asset repo.
CIQ_CORE_BINARY	unset	path	Uses an explicit core executable for local core development instead of the bundled binary.
CIQ_CORE_MANIFEST	unset	path	Optionally verifies `CIQ_CORE_BINARY` against a local core manifest rooted next to the platform directories.