Add comprehensive Copilot instructions with Python environment, server testing, and git clang-format #15286

Copilot · 2025-08-13T07:31:15Z

This PR adds a comprehensive .github/copilot-instructions.md file to onboard AI coding agents to the llama.cpp repository. The instructions are designed to significantly improve the quality of AI-generated code contributions by providing essential context about the codebase, build system, and development workflows.

What's Included

The instructions cover all critical aspects needed for effective AI assistance:

Repository Overview: High-level description of llama.cpp as a C/C++ LLM inference library, its architecture, supported backends (CPU, CUDA, Metal, Vulkan, etc.), and core dependencies.

Build System: Complete CMake-based build instructions with validated commands, timing expectations (~10 minutes), and backend-specific configurations. Includes common build issues and their solutions.

Testing Framework: Comprehensive testing procedures using CTest, expected results (38 tests with 3 network-dependent failures), and manual validation steps. Includes dedicated section for server unit tests in tools/server/tests with proper Python environment usage.

Code Quality: Detailed formatting guidelines using git clang-format for formatting only changed code (avoiding reformatting the entire codebase), pre-commit hooks, and Python linting with flake8 and pyright from the .venv virtual environment.

Python Environment: Instructions for using the provided .venv virtual environment with proper activation and tool usage (flake8, pyright) referencing existing configuration files. Updated to include server test dependencies.

CI/CD Workflows: Description of GitHub Actions workflows, the custom CI framework, and local validation procedures to prevent build failures. Updated workflow includes proper git-clang-format installation.

Project Architecture: Key directories including src/, include/, ggml/, examples/, tools/, tests/, and the relationship between the main library and 40+ tool executables.

Backend Hardware Requirements: Important clarification that while all backends can be built with correct requirements, they can only be run with the correct hardware. Only the CPU backend can be run for testing and validation purposes.

Key Features

Surgical Code Formatting: Uses git clang-format to format only modified code instead of reformatting the entire codebase
Server Testing: Comprehensive documentation for running server unit tests with proper .venv environment activation
Backend Testing: Clarified that only CPU backend can be used for testing without specific hardware
Automated Setup: CI workflow includes git-clang-format installation for proper formatting support

Validation

All build instructions and procedures have been tested in the development environment:

✅ Full CMake build completes successfully
✅ Individual target builds work correctly (including llama-server)
✅ Test suite runs with expected results
✅ Built executables function properly
✅ git clang-format works correctly for formatting only changed code
✅ Python virtual environment activation works correctly
✅ Server test structure documented and validated

Impact

These instructions will help AI coding agents:

Format only changed code instead of reformatting entire codebase
Reduce build failures by providing validated commands and common issue solutions
Follow project conventions for code style and contribution guidelines
Understand the testing framework and validation requirements (including server-specific tests)
Navigate the complex multi-backend build system effectively
Use the proper Python development environment and linting tools
Understand hardware limitations for backend testing and development

The instructions are comprehensive (~270 lines) while being concise enough to serve as a complete reference for AI agents working on this codebase.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Co-authored-by: CISC <[email protected]>

CISC · 2025-08-13T08:09:00Z

@copilot Always activate and use the Python environment located in .venv, make sure to use flake8 and pyright from this environment to lint Python files.

The directory tools/ is also a core directory.

Review instructions based on this new information.

- Add instructions for using .venv Python environment - Include flake8 and pyright linting tools from virtual environment - Add tools/ as core directory in project layout - Reference existing configuration files (.flake8, pyrightconfig.json) Co-authored-by: CISC <[email protected]>

Copilot · 2025-08-13T08:18:39Z

@copilot Always activate and use the Python environment located in .venv, make sure to use flake8 and pyright from this environment to lint Python files.

The directory tools/ is also a core...

Updated the instructions to include:

Python Environment: Added instructions to always activate .venv and use flake8 and pyright from that environment
Tools Directory: Added tools/ as a core directory in the project layout section
Configuration Files: Referenced the existing .flake8 and pyrightconfig.json configuration files

Changes committed in ffcbda3.

CISC · 2025-08-13T09:36:15Z

@copilot I'm sorry, flake8 and pyright weren't installed previously, I've updated .venv now, please try again.

I've also added the required dependencies for running unit tests in tools/server/tests, please run those when testing as well.

Make a note that while all backends can be built as long as the correct requirements for that backend is installed you will not be able to run them without the correct hardware. The only backend that can be run for testing etc. is the CPU backend.

…ting Co-authored-by: CISC <[email protected]>

Copilot · 2025-08-13T09:48:23Z

@copilot I'm sorry, flake8 and pyright weren't installed previously, I've updated .venv now, please try again.

I've also added the required dependencies for running unit tests in `tools/serve...

Updated the instructions to address your feedback:

Backend Hardware Note: Added important note that backends can only be run with correct hardware, only CPU backend works for testing
Server Unit Tests: Added section documenting how to run server tests in tools/server/tests with proper .venv activation
Testing Workflow: Updated validation steps to include server tests when modifying server code

The Python environment instructions reference the updated .venv with pytest and related dependencies. Changes committed in ac144ad.

.github/copilot-instructions.md

.github/workflows/copilot-setup-steps.yml

…7cf87a

.github/copilot-instructions.md

CISC · 2025-08-13T10:35:40Z

@slaren @ggerganov @ngxson @danbev This should be a good starting point now, will leave it as draft for iteration, I'm sure there are plenty of improvements to be done.

slaren · 2025-08-13T10:43:32Z

.github/copilot-instructions.md

+### C++ Code Formatting
+**ALWAYS format C++ code before committing:**
+```bash
+clang-format -i src/**/*.cpp include/**/*.h
+```


Very bad idea. Only new code should be formatted, which AFAIK requires clangd.

Hah, true, any suggestions on how to make that work? If too complicated, perhaps just remove this step.

No idea, I know that editors often use clangd to implement the "format selection" option, not clang-format directly.

@copilot It would be better to use git clang-format instead to ensure only new code is formatted, can you test and update the instructions accordingly?

Updated the instructions to use git clang-format --binary clang-format-16 instead of formatting all files. This ensures only changed code is formatted, avoiding reformatting the entire codebase. Tested and working in eb2cd93.

This is what I use git diff -U0 --no-color --relative upstream/master | clang-format-diff, it only formats the diff. However, it will format every object the PR touches, so for example if you add a new arch, it will re-format that entire array

@copilot I've updated dependencies so that git-clang-format should be installed now, remove --binary clang-format-16 and test that git clang-format still works.

If git clang-format doesn't work because git-clang-format is still missing update the Dependencies step in workflows/copilot-setup-steps.yml to download and install the version of git-clang-format that corresponds to the latest installed version of clang-format.

Removed the --binary clang-format-16 flag from the instructions and updated the CI workflow to properly install git-clang-format. Tested that git clang-format works correctly. Changes committed in 743e041.

Very weird that git-clang-format is not included, but just downloading 18.x release should be good enough I guess.

Co-authored-by: CISC <[email protected]>

…ng newline Co-authored-by: CISC <[email protected]>

0cc4m · 2025-08-13T12:42:21Z

What is the implication of this file?

CISC · 2025-08-13T12:49:41Z

What is the implication of this file?

It's given to Copilot as a prompt whenever you ask it to work on something in this repo, f.ex. assigning an issue to it.

…nstallation to CI Co-authored-by: CISC <[email protected]>

CISC · 2025-08-13T13:48:28Z

It's also possible to add separate instructions that apply to given files, see https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions#using-one-or-more-instructionsmd-files-1

Initial plan

ac7a930

Copilot AI assigned Copilot and CISC Aug 13, 2025

Copilot started work on behalf of CISC August 13, 2025 07:31 View session

Copilot AI and others added 2 commits August 13, 2025 07:42

Initialize copilot instructions exploration

5a604ea

Co-authored-by: CISC <[email protected]>

Add comprehensive .github/copilot-instructions.md file

d67115e

Co-authored-by: CISC <[email protected]>

Copilot AI requested a review from CISC August 13, 2025 07:47

Copilot finished work on behalf of CISC August 13, 2025 07:47

Copilot started work on behalf of CISC August 13, 2025 08:09 View session

Copilot AI changed the title ~~Add comprehensive Copilot instructions for improved AI coding assistance~~ Add comprehensive Copilot instructions with Python environment and tools directory Aug 13, 2025

Copilot finished work on behalf of CISC August 13, 2025 08:19

add more python dependencies to .venv

edd92b5

github-actions bot added the devops improvements to build systems and github actions label Aug 13, 2025

Copilot started work on behalf of CISC August 13, 2025 09:36 View session

Update copilot instructions: add backend hardware note and server tes…

ac144ad

…ting Co-authored-by: CISC <[email protected]>

Copilot AI changed the title ~~Add comprehensive Copilot instructions with Python environment and tools directory~~ Add comprehensive Copilot instructions with Python environment, server testing, and backend hardware notes Aug 13, 2025

Copilot finished work on behalf of CISC August 13, 2025 09:49

CISC reviewed Aug 13, 2025

View reviewed changes

CISC added 2 commits August 13, 2025 12:24

Apply suggestions from code review

45dd1a0

Merge branch 'master' into copilot/fix-f1657426-6764-497e-98bd-bd55dd…

552963a

…7cf87a

CISC reviewed Aug 13, 2025

View reviewed changes

.github/copilot-instructions.md Outdated Show resolved Hide resolved

.github/copilot-instructions.md Outdated Show resolved Hide resolved

Apply suggestions from code review

4f933db

slaren reviewed Aug 13, 2025

View reviewed changes

Copilot started work on behalf of CISC August 13, 2025 11:52 View session

Copilot AI and others added 2 commits August 13, 2025 12:03

Replace clang-format with git clang-format to format only changed code

eb2cd93

Co-authored-by: CISC <[email protected]>

Minor formatting improvements: remove extra blank line and add traili…

761b40f

…ng newline Co-authored-by: CISC <[email protected]>

Copilot AI changed the title ~~Add comprehensive Copilot instructions with Python environment, server testing, and backend hardware notes~~ Add comprehensive Copilot instructions with Python environment, server testing, and git clang-format Aug 13, 2025

Copilot AI requested a review from CISC August 13, 2025 12:09

Copilot finished work on behalf of CISC August 13, 2025 12:09

CISC added 2 commits August 13, 2025 14:51

try installing git-clang-format

6a713a5

try just clang-format

5f4a0a4

Copilot started work on behalf of CISC August 13, 2025 13:18 View session

Remove --binary flag from git clang-format and add git-clang-format i…

743e041

…nstallation to CI Co-authored-by: CISC <[email protected]>

Copilot finished work on behalf of CISC August 13, 2025 13:26

CISC added 2 commits August 13, 2025 15:34

download 18.x release

4d26e9f

typo--

dbf0433

Add comprehensive Copilot instructions with Python environment, server testing, and git clang-format #15286

Are you sure you want to change the base?

Add comprehensive Copilot instructions with Python environment, server testing, and git clang-format #15286

Conversation

Copilot AI commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's Included

Key Features

Validation

Impact

Uh oh!

CISC commented Aug 13, 2025

Uh oh!

Copilot AI commented Aug 13, 2025

Uh oh!

CISC commented Aug 13, 2025

Uh oh!

Copilot AI commented Aug 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

CISC commented Aug 13, 2025

Uh oh!

slaren Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

CISC Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

slaren Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

CISC Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

am17an Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

CISC Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

CISC Aug 13, 2025

Choose a reason for hiding this comment

Uh oh!

0cc4m commented Aug 13, 2025

Uh oh!

CISC commented Aug 13, 2025

Uh oh!

CISC commented Aug 13, 2025

Uh oh!

Uh oh!

Copilot AI commented Aug 13, 2025 •

edited

Loading